[U-Boot] [PATCH v2] ARM: socfpga: add fpga build and bsp handoff instructions to readme

[U-Boot] [PATCH v2] ARM: socfpga: add fpga build and bsp handoff instructions to readme

[Stephen Arnold]

This patch adds the steps to manually (re)build a Quartus FPGA project,
generate the required BSP glue, and update u-boot handoff files for
mainline SPL support. Requires Quartus toolchain and current U-Boot.

Signed-off-by: Steve Arnold <stephen.arnold42@gmail.com>
Cc: Dinh Nguyen <dinguyen@kernel.org>
Cc: Stefan Roese <sr@denx.de>
Cc: Marek Vasut <marex@denx.de>
---
Changes for v2:
   - Addressed comments by marex
   - Added some clarification
   - Made formatting a bit more rst-ish

 doc/README.socfpga | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 136 insertions(+), 5 deletions(-)

diff --git a/doc/README.socfpga b/doc/README.socfpga
index cb805cfd3a..cae0ef1a21 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 handoff header files for U-Boot SPL
+--------------------------------------------------
+
+This text is assuming quartus 16.1, but newer versions will probably work just fine too;
+verified with DE1_SOC_Linux_FB demo project (https://github.com/VCTLabs/DE1_SOC_Linux_FB).
+Updated/working projects should build using either process below.
+
+Note: it *should* work from Quartus 14.0.200 onwards, however, the current vendor demo
+projects must have the IP cores updated as shown below.
+
+Rebuilding your Quartus project
+-------------------------------
+
+Choose one of the follwing methods, either command line or GUI.
+
+Using the comaand line
+~~~~~~~~~~~~~~~~~~~~~~
+
+First run the embedded command shell, using your path to the Quartus install:
+
+  $ /path/to/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_sh --flow compile <project name>
+
+Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file):
+
+  $ quartus_cpf -c <project_name>.sof soc_system.rbf
+
+
+Generate BSP handoff files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can run the bsp editor GUI below, or 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
+
+You should use the bsp "build" directory 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.
+
+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 '<project_name>.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. Start the embedded command shell as shown in the previous section
+  6.1 Change directory to 'software/spl_bsp'
+  6.2 Prepare BSP by launching the BSP editor from ECS
+       => bsp-editor
+  6.3 In BSP editor
+      6.3.1 Use File -> Open
+      6.3.2 Select 'settings.bsp' file
+      6.3.3 Click Generate
+      6.3.4 Click Exit
+
+
+Post handoff generation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that the handoff files are generated, U-Boot can be used to process
+the handoff files generated by the bsp-editor. 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 files 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 (or update) the following 4 files:
+
+  iocsr_config.h
+  pinmux_config.h
+  pll_config.h
+  sdram_config.h
+
+These files should be copied into "qts" directory in the board directory
+(see output argument of qts-filter.sh command above).
+
+Here is an example for the DE-0 Nano SoC after the above rebuild process:
+
+  $ ll board/terasic/de0-nano-soc/qts/
+  total 36
+  -rw-r--r-- 1 sarnold sarnold 8826 Mar 21 18:11 iocsr_config.h
+  -rw-r--r-- 1 sarnold sarnold 4398 Mar 21 18:11 pinmux_config.h
+  -rw-r--r-- 1 sarnold sarnold 3190 Mar 21 18:11 pll_config.h
+  -rw-r--r-- 1 sarnold sarnold 9022 Mar 21 18:11 sdram_config.h
+
+Note: file sizes will differ slightly depending on the selected board.
+
+Now your board is ready for full mainline support including U-Boot SPL.
+The Preloader will not be needed any more.
-- 
2.11.1

[U-Boot] [PATCH v2] ARM: socfpga: add fpga build and bsp handoff instructions to readme

[Marek Vasut]

On 03/24/2017 02:58 AM, Stephen Arnold wrote:
> This patch adds the steps to manually (re)build a Quartus FPGA project,
> generate the required BSP glue, and update u-boot handoff files for
> mainline SPL support. Requires Quartus toolchain and current U-Boot.
> 
> Signed-off-by: Steve Arnold <stephen.arnold42@gmail.com>
> Cc: Dinh Nguyen <dinguyen@kernel.org>
> Cc: Stefan Roese <sr@denx.de>
> Cc: Marek Vasut <marex@denx.de>
> ---
> Changes for v2:
>    - Addressed comments by marex
>    - Added some clarification
>    - Made formatting a bit more rst-ish
> 
>  doc/README.socfpga | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 136 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/README.socfpga b/doc/README.socfpga
> index cb805cfd3a..cae0ef1a21 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 handoff header files for U-Boot SPL
> +--------------------------------------------------
> +
> +This text is assuming quartus 16.1, but newer versions will probably work just fine too;
> +verified with DE1_SOC_Linux_FB demo project (https://github.com/VCTLabs/DE1_SOC_Linux_FB).
> +Updated/working projects should build using either process below.
> +
> +Note: it *should* work from Quartus 14.0.200 onwards, however, the current vendor demo
> +projects must have the IP cores updated as shown below.
> +
> +Rebuilding your Quartus project
> +-------------------------------
> +
> +Choose one of the follwing methods, either command line or GUI.
> +
> +Using the comaand line
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +First run the embedded command shell, using your path to the Quartus install:
> +
> +  $ /path/to/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_sh --flow compile <project name>
> +
> +Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file):
> +
> +  $ quartus_cpf -c <project_name>.sof soc_system.rbf
> +
> +
> +Generate BSP handoff files
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +You can run the bsp editor GUI below, or 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
> +
> +You should use the bsp "build" directory 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.
                               ^^^
                               just soc , not sockit .

Fixed and applied, thanks!

-- 
Best regards,
Marek Vasut