diff mbox series

[2/4] doc: README.socfpga: Add guide for mkimage

Message ID 20221113135536.9920-2-jit.loon.lim@intel.com
State Needs Review / ACK, archived
Delegated to: Marek Vasut
Headers show
Series [1/4] makefile: tools: socfpgaimage: update padding flow | expand

Commit Message

Jit Loon Lim Nov. 13, 2022, 1:55 p.m. UTC
From: Ley Foon Tan <ley.foon.tan@intel.com>

HSD #1508690657-3: Add guide for mkimage for Cyclone V, Arria V and Arria 10.

Signed-off-by: Ley Foon Tan <ley.foon.tan@intel.com>
Signed-off-by: Jit Loon Lim <jit.loon.lim@intel.com>
---
 doc/README.socfpga | 317 +++++++++++++++++++++++++++------------------
 1 file changed, 193 insertions(+), 124 deletions(-)
diff mbox series

Patch

diff --git a/doc/README.socfpga b/doc/README.socfpga
index 4d73398eb9..a469cc7e41 100644
--- a/doc/README.socfpga
+++ b/doc/README.socfpga
@@ -1,178 +1,247 @@ 
-----------------------------------------
+---------------------------------------------------------------------
 SOCFPGA Documentation for U-Boot and SPL
-----------------------------------------
+---------------------------------------------------------------------
+
+This README is about U-Boot and SPL support for Intel SOCFPGA.
+To know more about the hardware itself, please refer to
+https://www.intel.com/content/www/us/en/products/programmable/soc.html
+
+
+Table of Contents
+---------------------------------------------------------------------
+	1. Device Family Support vs Tested Intel Quartus
+	2. Feature Support
+	3. Major Changes and Known Issues
+	4. Cyclone V / Arria V generating the handoff header files for U-Boot SPL
+	5. Arria10 generating the handoff header files for U-Boot SPL
+	6. mkimage for Cyclone V, Arria V and Arria 10
 
-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.
 
+1. Device Family Support vs Tested Intel Quartus
+---------------------------------------------------------------------
 
-socfpga_dw_mmc
---------------
+	Processor			SOCFPGA Device Family		Intel Quartus Prime Pro Edition		Intel Quartus Prime Standard Edition	
+	--------------------------------------------------------------------------------------------------------------------------------------------
+	Dual-core ARM Cortex-A9		Cyclone V			N/A					20.1
+					Arria V				N/A					20.1
+					Arria 10			20.1, 20.3				20.1
 
-Here are macro and detailed configuration required to enable DesignWare SDMMC
-controller support within SOCFPGA
+	Quad-core ARM Cortex-A53	Stratix 10			20.1, 20.2, 20.3			N/A
+					Agilex				20.1, 20.2, 20.3			N/A
+					Diamond Mesa			Early access				N/A
 
-#define CONFIG_SYS_MMC_MAX_BLK_COUNT	256
--> Using smaller max blk cnt to avoid flooding the limited stack in OCRAM
 
+2. Feature Support
 ---------------------------------------------------------------------
-Cyclone 5 / Arria 5 generating the handoff header files for U-Boot SPL
+
+	Hardware Feature			Cyclone V	Arria 10	Stratix 10	Agilex		Diamond Mesa
+						Arria V
+	--------------------------------------------------------------------------------------------------------------------
+	SDRAM					Yes		Yes		Yes		Yes		Yes
+	HPS bridge (LWH2F, H2F, F2S)		Yes		Yes		Yes		Yes		Yes
+	HPS cold/warm reset			Yes		Yes		Yes		Yes		Yes
+	FPGA configuration			Yes		Yes		Yes		Yes		No
+	Partial reconfiguration			No		No		Yes		No		No
+	Ethernet (Synopsys EMAC controller)	Yes		Yes		Yes		Yes		Yes
+	Synopsys GPIO controller		Yes		Yes		Yes		Yes		Yes
+	Synopsys UART controller		Yes		Yes		Yes		Yes		Yes
+	Synopsys USB controller			Yes		Yes		Yes		Yes		Yes
+	Synopsys Watchdog timer			Yes		Yes		Yes		Yes		Yes
+	Synopsys I2C master controller		Yes		No		Yes		Yes		Yes
+	Synopsys SDMMC controller		Yes		Yes		Yes		Yes		Yes
+	Cadence QSPI controller			Yes		Yes		Yes		Yes		Yes
+	Denali NAND controller			No		Yes		Yes		Yes		Yes
+	---------------------------------------------------------------------------------------------------------------------
+
+	Software Feature			Cyclone V	Arria 10	Stratix 10	Agilex		Diamond Mesa
+						Arria V
+	---------------------------------------------------------------------------------------------------------------------
+	Remote System Update (RSU)		No		No		Yes		Yes		No
+	ARM Trusted Firmware (ATF)		No		No		Yes		Yes		Yes
+	Vendor Authorized Boot (VAB)		No		No		No		No		Yes
+	---------------------------------------------------------------------------------------------------------------------
+
+
+3. Major Changes and Known Issues
 ---------------------------------------------------------------------
 
-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.
+	3.1 Support 'vab' command to perform vendor authentication.
+
+		Command format: vab addr len
+		Authorize 'len' bytes starting at 'addr' via vendor public key
 
-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.
+	3.2 Support SDRAM secure region in U-boot-ATF flow
 
-Rebuilding your Quartus project
--------------------------------
+		First 1 MiB of SDRAM is configured as secure region, other
+		address spaces are non-secure regions. Only software executing
+		at secure state EL3 (eg: U-boot SPL) and secure masters are
+		allowed access to secure region.
 
-Choose one of the follwing methods, either command line or GUI.
 
-Using the command line
-~~~~~~~~~~~~~~~~~~~~~~
+4. Cyclone V / Arria V generating the handoff header files for U-Boot SPL
+---------------------------------------------------------------------
 
-First run the embedded command shell, using your path to the Quartus install:
+	Rebuilding your Quartus project
+	-------------------------------
 
-  $ /path/to/intelFPGA/16.1/embedded/embedded_command_shell.sh
+	Choose one of the follwing methods, either command line or GUI.
 
-Then (if necessary) update the IP cores in the project, generate HDL code, and
-build the project:
+	Using the command line
+	~~~~~~~~~~~~~~~~~~~~~~
 
-  $ 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>
+	First run the embedded command shell, using your path to the Quartus install:
 
-Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file):
+	  $ /path/to/intelFPGA/16.1/embedded/embedded_command_shell.sh
 
-  $ quartus_cpf -c <project_name>.sof soc_system.rbf
+	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>
 
-Generate BSP handoff files
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+	Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file):
 
-You can run the bsp editor GUI below, or run the following command from the
-project directory:
+	  $ quartus_cpf -c <project_name>.sof soc_system.rbf
 
-  $ /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.
+	Generate BSP handoff files
+	~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now you can skip the GUI section.
+	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
 
-Using the Qsys GUI
-~~~~~~~~~~~~~~~~~~
+	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.
 
-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)
+	Now you can skip the GUI section.
 
-    ... 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
+	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)
 
-Post handoff generation
-~~~~~~~~~~~~~~~~~~~~~~~
+	    ... this may take some time, have patience ...
 
-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:
+	6. Start the embedded command shell as shown in the previous section
 
-  $ ./arch/arm/mach-socfpga/qts-filter.sh \
-        <soc_type> \
-        <input_qts_dir> \
-        <input_bsp_dir> \
-        <output_dir>
+	  $ /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
 
-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.
+	Post handoff generation
+	~~~~~~~~~~~~~~~~~~~~~~~
 
-This will generate (or update) the following 4 files:
+	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:
 
-  iocsr_config.h
-  pinmux_config.h
-  pll_config.h
-  sdram_config.h
+	  $ ./arch/arm/mach-socfpga/qts-filter.sh \
+		<soc_type> \
+		<input_qts_dir> \
+		<input_bsp_dir> \
+		<output_dir>
 
-These files should be copied into "qts" directory in the board directory
-(see output argument of qts-filter.sh command above).
+	Process QTS-generated files into U-Boot compatible ones.
 
-Here is an example for the DE-0 Nano SoC after the above rebuild process:
+	    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.
 
-  $ 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
+	This will generate (or update) the following 4 files:
 
-Note: file sizes will differ slightly depending on the selected board.
+	  iocsr_config.h
+	  pinmux_config.h
+	  pll_config.h
+	  sdram_config.h
 
-Now your board is ready for full mainline support including U-Boot SPL.
-The Preloader will not be needed any more.
+	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.
+	      For SoC devkit please refer to https://rocketboards.org/foswiki/Documentation/BuildingBootloader#Cyclone_V_SoC_45_Boot_from_SD_Card
+
+	Now your board is ready for full mainline support including U-Boot SPL.
+	The Preloader will not be needed any more.
+
+
+5. Arria10 generating the handoff header files for U-Boot SPL
 ----------------------------------------------------------
-Arria 10 generating the handoff header files for U-Boot SPL
-----------------------------------------------------------
 
-A header file for inclusion in a devicetree for Arria10 can be generated
-by the qts-filter-a10.sh script directly from the hps_isw_handoff/hps.xml
-file generated during the FPGA project compilation.  The header contains
-all PLL, clock, pinmux, and bridge configurations required.
+	A header file for inclusion in a devicetree for Arria10 can be generated
+	by the qts-filter-a10.sh script directly from the hps_isw_handoff/hps.xml
+	file generated during the FPGA project compilation.  The header contains
+	all PLL, clock, pinmux, and bridge configurations required.
+
+	Please look at the socfpga_arria10_socdk_sdmmc-u-boot.dtsi for an example
+	that includes use of the generated handoff header.
+
+	Devicetree header generation
+	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Please look at the socfpga_arria10_socdk_sdmmc-u-boot.dtsi for an example
-that includes use of the generated handoff header.
+	The qts-filter-a10.sh script can process the compile time genetated hps.xml
+	to create the appropriate devicetree header.
 
-Devicetree header generation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The qts-filter-a10.sh script can process the compile time genetated hps.xml
-to create the appropriate devicetree header.
+	  $ ./arch/arm/mach-socfpga/qts-filter-a10.sh \
+		<hps_xml> \
+		<output_file>
+
+	    hps_xml      - hps_isw_handoff/hps.xml from Quartus project
+	    output_file  - Output filename and location for header file
+
+	The script generates a single header file names <output_file> that should
+	be placed in arch/arm/dts.
+
+6. mkimage for Cyclone V, Arria V and Arria 10
+----------------------------------------------------------
+
+	The mkimage tool creates an Intel BootROM compatible image of the
+	Cyclone V SoC, Arria V SoC or Arria 10 SoC bootloader. mkimage is invoked
+	automatically in default U-boot building proccess. To create BootROM
+	compatible image manually, user can run example below:
 
+	./tools/mkimage -T <type> -d <input file> <output file>
 
-  $ ./arch/arm/mach-socfpga/qts-filter-a10.sh \
-        <hps_xml> \
-        <output_file>
+	Cyclone V and Arria V:
+	./tools/mkimage -T socfpgaimage -d spl/u-boot-spl.bin spl/u-boot-spl.sfp
 
-    hps_xml      - hps_isw_handoff/hps.xml from Quartus project
-    output_file  - Output filename and location for header file
+	Arria 10:
+	./tools/mkimage -T socfpgaimage_v1 -d spl/u-boot-spl.bin spl/u-boot-spl.sfp
 
-The script generates a single header file names <output_file> that should
-be placed in arch/arm/dts.
+	For more inforation, run "./tools/mkimage --help".
\ No newline at end of file