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

[Marek Vasut]

On 03/10/2017 09:03 PM, Steve Arnold wrote:
> From: Steve Arnold <stephen.arnold42 at gmail.com>

Hi!

lots of nitpicks below, but it really is starting to get into a good
shape, thanks for the work and sorry for my delayed reply.

> This patch adds back the steps to manually (re)build a Quartus FPGA
                  ^
                  '- back? It's not like we ever had those in ...

> 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.

Which was based on earlier docs by me, but do we really need that info
in commit message ?

> 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
> +-----------------------------------------------------------------------------------

"integration" (type) , but you can reword it in much shorter way

Generating the handoff header files for U-Boot SPL

> +This text has been updated based on testing with Quartus Lite 16.1 and a rebuilt

This text is assuming quartus 16.1 , but newer versions will probably
work just fine too.

> +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.

You should make it clear that the user should use his own quartus
project for his own board here.

> +Note: it *should* work from Quartus 14.0.200 onwards.
> +
> +Rebuilding your Quartus project
> +-------------------------------
> +
> +Using the cli

command line instead of cli please

> +~~~~~~~~~~~~~
> +
> +First run the embedded command shell, using your path to the Quartus install:
> +
> +  $ ${HOME}/intelFPGA/16.1/embedded/embedded_command_shell.sh

Replace ${HOME} with /path/to/ , since the tools are usually not
installed in ~

> +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>

You can replace the last three with

$ quartus_sh --flow compile <project name>

> +Convert the .sof file to a firmware blob:
> +
> +  $ quartus_cpf -c <project_name>.sof soc_system.rbf

Convert the .sof file (SRAM object file) to .rbf file (Raw bit file):

> +Now you can skip the GUI section.

OK

> +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'

probably not mcv_hps.qsys , right ?

> +    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

Here you're entering the embedded command shell again, see the command
line section above , we should make sure this bit of documentation is
not duplicated.

> +    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

Generate BSP handoff files ?

Shouldn't this be part of the command line section above ? Since the GUI
section documents this functionality using GUI tool

> +~~~~~~~~~~~~~~~~
> +
> +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:

It has nothing to do with u-boot , this is still bsp-editor :)

> +  $ /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

s/dir/directory/

> +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.

There is no de0-nano-sockit, there's either sockit or de0-nano , pick one.

> +
> +
> +Update U-Boot headers

Handoff files please , not headers .

> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Now the necessary files are generated. And U-Boot can be used to generate 
> +the SPL header files.

The qts-filter script (which is part of U-Boot tree) is used to process
the handoff files generated by 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 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:

That's DE0-Nano-SoC , not 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

The sizes don't match what's in mainline u-boot ;-)

> +Now your board is ready for full mainline support including U-Boot SPL.
> +The Preloader will not be needed any more.

-- 
Best regards,
Marek Vasut