Documentation: boards: add socfpga

Signed-off-by: Steffen Trumtrar <s.trumtrar@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

1 files changed, 80 insertions, 0 deletions

diff --git a/Documentation/boards/socfpga.rst b/Documentation/boards/socfpga.rst
new file mode 100644
index 0000000000..93831c5f29
--- /dev/null
+++ b/Documentation/boards/socfpga.rst
@@ -0,0 +1,80 @@
+Altera SoCFPGA
+==============
+
+Alteras SoCFPGA SoCs have a two-stage boot process. The first stage is
+known as preloader which loads the second stage bootloader. barebox can act
+as both the first and the second stage loader.
+In barebox the preloader is called xload, so to build as a first stage loader,
+build the ``socfpga-xload_defconfig``; for second stage use the normal
+``socfpga_defconfig``.
+
+Bootstrapping
+-------------
+
+The supported bootsource is a SD card. The Boot ROM searches for a partition of
+type A2 and loads what it finds there. When barebox is placed in such a partition
+it will then itself try and mount the second partition of the SD card, which must
+be of type FAT32. On this partition barebox searches for a file called barebox.bin.
+
+To boot barebox on a Terasic SoCkit, the procedure is as follows (sdb1 is the A2 and
+sdb2 the FAT32 partition)::
+
+  mount -t fat /dev/sdb2 /mnt
+  make socfpga-xload_defconfig
+  make
+  make socfpga_defconfig
+  make
+
+barebox has now generated multiple files in the images directory. So for the SoCkit
+proceed with::
+
+  cat images/barebox-socfpga-sockit-xload.img > /dev/sdb1
+  cp images/barebox-socfpga-sockit.img /mnt/barebox.bin
+  umount /mnt
+
+For the EBV Socrates use ``images/barebox-socfpga-socrates(-xload).img`` instead.
+
+Updating handoff files
+----------------------
+
+(Tools needed: Quartus II + SoCEDS)
+
+As barebox uses some of the autogenerated files from Quartus II, every
+time Altera makes a new release, there might be some updates to the
+handoff files. As these files are split up in the code base and generated
+explicitely for some specific U-boot code base, some manual work might be
+necessary.
+
+The following files are generic and belong into the
+`arch/arm/mach-socfpga` directory tree:
+
+* sequencer.c (Not for the faint of heart.)
+* sequencer.h
+* system.h
+
+It should normally not be necessary to touch these if barebox is up-to-date.
+
+The boardspecific files for `arch/arm/boards/<yourboard>` are:
+
+* iocsr_config_cyclone5.c
+* pinmux_config_cyclone5.c -> pinmux_config.c
+* pll_config.h
+* sdram/sdram_config.h -> sdram_config.h
+* sequencer_auto.h
+* sequencer_auto_ac_init.c
+* sequencer_auto_inst_init.c
+* sequencer_defines.h
+
+To update the handoff files, the following procedure is necessary::
+
+ 1. Regenerate the project with Qsys
+ 2. Load up your project in Quartus II and assemble the design
+ 3. Go to the SoCEDS installation and run
+    ``./embedded_command_shell.sh``
+ 4. Now run ``bsp-editor``
+ 5. Create a new BSP
+ 6. Select the directory `hps_isw_handoff/soc_system_hps_0` under the
+    preloader settings directory
+ 7. Click ``Ok`` than ``Generate``
+ 8. Copy the files generated in `software/spl_bsp/generated/` to your
+    board folder