[U-Boot] [PATCH] ARM: socfpga: Update README with BSP/header generation instructions

[Steve Arnold]

From: Steve Arnold <stephen.arnold42 at gmail.com>

This patch adds back the steps to manually (re)build a Quartus FPGA
project, generate the required BSP glue, and update u-boot headers
for mainline SPL support (updated from an earlier patch submitted
by Stefan Roese).  Requires Quartus toolchain and current U-Boot.

Signed-off-by: Steve Arnold <stephen.arnold42 at gmail.com>
Cc: Dinh Nguyen <dinguyen at kernel.org>
Cc: Stefan Roese <sr at denx.de>
Cc: Marek Vasut <marex at denx.de>
---
 doc/README.socfpga | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 136 insertions(+), 5 deletions(-)

diff --git a/doc/README.socfpga b/doc/README.socfpga
index cb805cfd3a..4783fdc52f 100644
--- a/doc/README.socfpga
+++ b/doc/README.socfpga
@@ -1,18 +1,149 @@
-
---------------------------------------------
+----------------------------------------
 SOCFPGA Documentation for U-Boot and SPL
---------------------------------------------
+----------------------------------------
 
 This README is about U-Boot and SPL support for Altera's ARM Cortex-A9MPCore
 based SOCFPGA. To know more about the hardware itself, please refer to
 www.altera.com.
 
 
---------------------------------------------
 socfpga_dw_mmc
---------------------------------------------
+--------------
+
 Here are macro and detailed configuration required to enable DesignWare SDMMC
 controller support within SOCFPGA
 
 #define CONFIG_SYS_MMC_MAX_BLK_COUNT	256
 -> Using smaller max blk cnt to avoid flooding the limited stack in OCRAM
+
+-----------------------------------------------------------------------------------
+Generating the header files for SPL intergration as a replacement for the Preloader
+-----------------------------------------------------------------------------------
+
+This text has been updated based on testing with Quartus Lite 16.1 and a rebuilt
+DE1_SOC_Linux_FB demo project (https://github.com/VCTLabs/DE1_SOC_Linux_FB). The
+FB project can now be built manually (as below) or with the project Makefile.
+
+Note: it *should* work from Quartus 14.0.200 onwards.
+
+Rebuilding your Quartus project
+-------------------------------
+
+Using the cli
+~~~~~~~~~~~~~
+
+First run the embedded command shell, using your path to the Quartus install:
+
+  $ ${HOME}/intelFPGA/16.1/embedded/embedded_command_shell.sh
+
+Then (if necessary) update the IP cores in the project, generate HDL code, and
+build the project:
+
+  $ cd path/to/project/dir
+  $ qsys-generate soc_system.qsys --upgrade-ip-cores
+  $ qsys-generate soc_system.qsys --synthesis=[VERILOG|VHDL]
+  $ quartus_map <project_name>
+  $ quartus_fit <project_name>
+  $ quartus_asm <project_name>
+
+Convert the .sof file to a firmware blob:
+
+  $ quartus_cpf -c <project_name>.sof soc_system.rbf
+
+Now you can skip the GUI section.
+
+Using the Qsys GUI
+~~~~~~~~~~~~~~~~~~
+
+ 1) Navigate to your project directory
+ 2) Run Quartus II
+ 3) Open Project (Ctrl+J), select <project_name>.qpf
+ 4) Run QSys [Tools->QSys]
+    4.1) In the Open dialog, select 'mcv_hps.qsys'
+    4.2) In the Open System dialog, wait until completion and press 'Close'
+    4.3) In the Qsys window, click on 'Generate HDL...' in bottom right corner
+         4.3.1) In the 'Generation' window, click 'Generate'
+	 4.3.2) In the 'Generate' dialog, wait until completion and click 'Close'
+    4.4) In the QSys window, click 'Finish'
+         4.4.1) In the 'Quartus II' pop up window, click 'OK'
+ 5) Back in Quartus II main window, do the following
+    5.1) Use Processing -> Start -> Start Analysis & Synthesis (Ctrl+K)
+    5.2) Use Processing -> Start Compilation (Ctrl+L)
+    ... this may take some time, have patience ...
+
+ 6) Launch a separate terminal window
+    6.1) Change directory to 'software/spl_bsp'
+    6.2) Export path to embedded command shell and friends
+         $ export PATH=path/to/quartus/embedded/:$PATH
+    6.3) Start embedded command shell (ECS)
+         $ embedded_command_shell.sh
+    6.4) Prepare BSP by launching the BSP editor from ECS
+         => bsp-editor
+    6.5) In BSP editor
+         6.5.1) Use File -> Open
+	 6.5.2) Select 'settings.bsp' file
+	 6.5.4) Click Generate
+	 6.5.5) Click Exit
+
+Generate BSP dir
+~~~~~~~~~~~~~~~~
+
+You can run the bsp editor GUI above, but the easy way for u-boot is to run the
+following command from the project directory:
+
+  $ /path/to/bsb/tools/bsp-create-settings --type spl --bsp-dir build \
+      --preloader-settings-dir hps_isw_handoff/soc_system_hps_0/ \
+      --settings build/settings.bsp
+
+Now you can use the "build" dir above (ie, where the settings.bsp file is) in
+the following u-boot command to update the board headers.  Once these headers
+are updated for a given project build, u-boot should be configured for the
+project board (eg, de0-nano-sockit) and then build the normal spl build.
+
+
+Update U-Boot headers
+~~~~~~~~~~~~~~~~~~~~~
+
+Now the necessary files are generated. And U-Boot can be used to generate 
+the SPL header files. For this, please use the following script from the
+u-boot source tree:
+
+  $ ./arch/arm/mach-socfpga/qts-filter.sh \
+        <soc_type> \
+        <input_qts_dir> \
+        <input_bsp_dir> \
+        <output_dir>
+
+Process QTS-generated headers into U-Boot compatible ones.
+
+    soc_type      - Type of SoC, either 'cyclone5' or 'arria5'.
+    input_qts_dir - Directory with compiled Quartus project
+                    and containing the Quartus project file (QPF).
+    input_bsp_dir - Directory with generated bsp containing
+                    the settings.bsp file.
+    output_dir    - Directory to store the U-Boot compatible
+                    headers.
+
+This will generate the following 4 files:
+
+iocsr_config.h
+pinmux_config.h
+pll_config.h
+sdram_config.h
+
+These files need to be copied into "qts" directory in the board directory
+(see output argument of qts-filter.sh command above).
+
+Here is the example for the DE-0 Nano SocKit:
+
+$ ll board/terasic/de0-nano-soc/qts/
+total 44
+drwxrwxr-x 2 stefan stefan 4096 Okt 20 07:07 ./
+drwxrwxr-x 3 stefan stefan 4096 Okt 21 13:06 ../
+-rw-rw-r-- 1 stefan stefan 8826 Okt 20 07:07 iocsr_config.h
+-rw-rw-r-- 1 stefan stefan 4398 Okt 20 07:07 pinmux_config.h
+-rw-rw-r-- 1 stefan stefan 3192 Okt 20 07:07 pll_config.h
+-rw-rw-r-- 1 stefan stefan 9031 Okt 20 07:07 sdram_config.h
+
+Now your board is ready for full mainline support including U-Boot SPL.
+The Preloader will not be needed any more.
-- 
2.11.0