Pulled from official Altera trunk and modified the handoff section. New handoff tool location and operations are explained accordingly.
Signed-off-by: Brian Sune <[email protected]> --- doc/README.socfpga | 412 ++++++++++++++++++++++++++++++++------------- 1 file changed, 295 insertions(+), 117 deletions(-) diff --git a/doc/README.socfpga b/doc/README.socfpga index e5adb62102b..ae87f4cd9da 100644 --- a/doc/README.socfpga +++ b/doc/README.socfpga @@ -1,168 +1,346 @@ ----------------------------------------- +--------------------------------------------------------------------- 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. +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 --------------------------------------------------------------------- -Cyclone 5 / Arria 5 generating the handoff header files for U-Boot SPL + 1. Device Family Support vs Tested Intel Quartus + 2. Feature Support + 3. Major Changes and Known Issues + 4. Git branch naming convention + 5. Cyclone V / Arria V generating the handoff header files for U-Boot SPL + 6. Arria10 generating the handoff header files for U-Boot SPL + 7. mkimage for Cyclone V, Arria V and Arria 10 + 8. SDRAM secure region in U-boot ATF flow + 9. binman for U-boot ATF flow + + +1. Device Family Support vs Tested Intel Quartus --------------------------------------------------------------------- -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. + Processor SOCFPGA Device Family Intel Quartus Prime Pro Edition Intel Quartus Prime Standard Edition + -------------------------------------------------------------------------------------------------------------------------------------------- + Dual-core ARM Cortex-A9 Cyclone V N/A 22.1 + Arria 10 23.2 N/A + + Quad-core ARM Cortex-A53 Stratix 10 23.2 N/A + Agilex 23.2 N/A + eASIC N5X 23.2 N/A + + +2. Feature Support +--------------------------------------------------------------------- -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. + Hardware Feature Cyclone V Arria 10 Stratix 10 Agilex eASIC N5X + 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 Yes 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 Yes 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 eASIC N5X + Arria V + --------------------------------------------------------------------------------------------------------------------- + Remote System Update (RSU) [1] No No Yes Yes No + ARM Trusted Firmware (ATF) [2] No No Yes Yes Yes + Vendor Authorized Boot (VAB) No No No No Yes + --------------------------------------------------------------------------------------------------------------------- + + Notes: + [1] RSU SPT/CPB recovery features are supported with Quartus version 20.4 onwards + [2] ATF boot flow is supported with altera-opensource/arm-trusted-firmware branch:socfpga_v2.3 onwards + + +3. Major Changes and Known Issues +--------------------------------------------------------------------- -Rebuilding your Quartus project -------------------------------- + 3.1 Upgraded U-boot to version v2023.04 -Choose one of the follwing methods, either command line or GUI. -Using the command line -~~~~~~~~~~~~~~~~~~~~~~ -First run the embedded command shell, using your path to the Quartus install: +4. Git branch naming convention +--------------------------------------------------------------------- + This convention is important to direct all users of Intel SOCFPGA U-Boot repository to use + the appropriate branch. + + The syntax of branch naming will be "socfpga_v[year].[month][_RC]". For example, + "socfpga_v2021.04_RC" or "socfpga_v2021.01" + Where, + [year] is the year of the branch released. + [month] is the month of the branch released. + [_RC] is the label for branch categories, optional, based on the branch categories below. + + Generally, branches in Intel SOCFPGA U-Boot repository can be distincted into TWO categories, + which are with and without "RC" labeled. + + Branch with "RC" labeled + ~~~~~~~~~~~~~~~~~~~~~~~~ + A "RC" labeled branch is for Intel internal active development use and customer early access + for latest updates without official customer support. Since this "RC" labeled branch is still + comes with active development, the branch release with latest year and month. There will be + always only ONE branch labeled with "RC" in Intel SOCFPGA U-Boot repository. + + Branch without "RC" labeled + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Latest stable branch (no RC labeled) is strongly recommended for any development and + production use outside of Intel. Only stable branches will be supported by official + customer support. + + +5. Cyclone V / Arria V generating the handoff header files for U-Boot SPL +--------------------------------------------------------------------- - $ /path/to/intelFPGA/16.1/embedded/embedded_command_shell.sh + Rebuilding your Quartus project + ------------------------------- -Then (if necessary) update the IP cores in the project, generate HDL code, and -build the project: + Choose one of the following methods, either command line or GUI. - $ 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> + Using the command line + ~~~~~~~~~~~~~~~~~~~~~~ -Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file): + First run the embedded command shell, using your path to the Quartus install: - $ quartus_cpf -c <project_name>.sof soc_system.rbf + $ /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: -Generate BSP handoff files -~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ 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> -You can run the bsp editor GUI below, or run the following command from the -project directory: + Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file): - $ /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 + $ quartus_cpf -c <project_name>.sof soc_system.rbf -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. + Generate BSP handoff files + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + There are two forms to run the handoff script. + Method 1 - directly call from tools: + $ python ./tools/cv_bsp_generator/cv_bsp_generator.py \ + -i <path_to_qpds_handoff>/hps_isw_handoff/<foo bar> \ + -o board/<vendor name>/<board name>/qts -Using the Qsys GUI -~~~~~~~~~~~~~~~~~~ + Method 2 + $ # general make command with auto config board detection + $ make prepare + $ # user path define with make + $ make prepare HANDOFF_PATH=<handoff folder path> + $ # user path export + $ export HANDOFF_PATH=<handoff folder path> + $ make prepare -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) + The generated files are uboot-compatible. They will be located in \ + board/<board vendor>/<platform_type>/qts. These files will be used for SPL \ + generation. - ... this may take some time, have patience ... + Argument: -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 + -i - Directory with QPDS handoff path. + -o - Directory to store the U-Boot compatible headers. + This will generate (or update) the following 4 files: -Post handoff generation -~~~~~~~~~~~~~~~~~~~~~~~ + iocsr_config.h + pinmux_config.h + pll_config.h + sdram_config.h -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: + These files should be copied into "qts" directory in the board directory + (see output argument of cv_bsp_generator.py command above). - $ ./arch/arm/mach-socfpga/qts-filter.sh \ - <soc_type> \ - <input_qts_dir> \ - <input_bsp_dir> \ - <output_dir> + Here is an example for the DE-0 Nano SoC after the above rebuild process: -Process QTS-generated files into U-Boot compatible ones. + $ 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 - 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. + 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 -This will generate (or update) the following 4 files: + Now your board is ready for full mainline support including U-Boot SPL. + The Preloader will not be needed any more. - 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). +6. Arria10 generating the handoff header files for U-Boot SPL +---------------------------------------------------------- -Here is an example for the DE-0 Nano SoC after the above rebuild process: + 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. - $ 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 + Please look at the socfpga_arria10_socdk_sdmmc-u-boot.dtsi for an example + that includes use of the generated handoff header. -Note: file sizes will differ slightly depending on the selected board. + Devicetree header generation + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Now your board is ready for full mainline support including U-Boot SPL. -The Preloader will not be needed any more. + 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. + +7. mkimage for Cyclone V, Arria V and Arria 10 ---------------------------------------------------------- -Arria 10 generating the handoff header files for U-Boot SPL + + 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> + + Cyclone V and Arria V: + ./tools/mkimage -T socfpgaimage -d spl/u-boot-spl.bin spl/u-boot-spl.sfp + + Arria 10: + ./tools/mkimage -T socfpgaimage_v1 -d spl/u-boot-spl.bin spl/u-boot-spl.sfp + + For more inforation, run "./tools/mkimage --help". + +8. SDRAM secure region in U-boot ATF flow ---------------------------------------------------------- -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. + In boot flow that uses ATF (ARM trusted firmware), the 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, ATF) and secure + masters are allowed access to the secure region. + +9. binman for U-boot ATF flow +---------------------------------------------------------- + + Overview + ~~~~~~~~ + + Before v2021.04, we provide *.sh/*.its for user to generate FIT image using + 'mkimage' tool. To align with U-Boot community strategy to eliminate the custom + *.sh/*its script, we have removed all *.sh/*.its files and switched to use + 'binman' tool to generate FIT image for all SOC64 devices (Stratix 10, Agilex, + eASIC N5X) started in U-boot version v2021.04. + + FIT image content is defined in binman node in U-boot device tree (u-boot.dtb). + U-Boot v2021.04 support u-boot.itb and kernel.itb. + + With "CONFIG_BINMAN" enabled in deconfig, U-boot will always run 'binman' tool + before end of the code compilation. If the required input files exists in U-boot + folder, *.itb files defined in u-boot.dtb will be generated. Otherwise, 'binman' + will not generate the *.itb files. You can run 'binman' tool manually via command + line to generate the *.itb file. + + Input Files + ~~~~~~~~~~~ + + Input files for *_atf_defconfig FIT image generation: + To generate u-boot.itb: + u-boot-nodtb.bin + u-boot.dtb + bl31.bin + To generate kernel.itb: + Image + linux.dtb -Please look at the socfpga_arria10_socdk_sdmmc-u-boot.dtsi for an example -that includes use of the generated handoff header. + Input files for *_vab_defconfig FIT image generation: + To generate u-boot.itb: + signed-u-boot-nodtb.bin + signed-u-boot.dtb + signed-bl31.bin -Devicetree header generation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To generate kernel.itb: + signed-Image + signed-linux.dtb -The qts-filter-a10.sh script can process the compile time genetated hps.xml -to create the appropriate devicetree header. + Command Line + ~~~~~~~~~~~~ + Please use the following commands to generate the u-boot.itb and kernel.itb: - $ ./arch/arm/mach-socfpga/qts-filter-a10.sh \ - <hps_xml> \ - <output_file> + $ <U-boot path>/tools/binman/binman build -u -d u-boot.dtb -O . + This command generate all FIT images that defined in device tree. - hps_xml - hps_isw_handoff/hps.xml from Quartus project - output_file - Output filename and location for header file + $ <U-boot path>/tools/binman/binman build -u -d u-boot.dtb -O . -i u-boot + This command generate u-boot.itb only. -The script generates a single header file names <output_file> that should -be placed in arch/arm/dts. + $ <U-boot path>/tools/binman/binman build -u -d u-boot.dtb -O . -i kernel + This command generate kernel.itb only. + +9. Official Boot-up Flow Support +--------------------------------------------------------------------- + U-boot with Arm Trusted Firmware (ATF, TF-A) boot-up is the official supported + boot flow for Intel SoC FPGA Arm 64-bit architecture devices including + Stratix 10, Agilex and N5X. ATF is the secure runtime firmware running at EL3 + which handles secure accesses from U-boot proper and Linux running at EL2 and EL1. + + Official boot flow: + U-boot -> ATF BL31 -> U-boot proper -> Linux + + Legacy (aka non ATF) boot flow: + U-boot -> U-boot proper -> Linux + + U-boot version socfpga_v2021.07 and onwards change the defconfig name to match + the official boot flow. The non ATF flow defconfigs are renamed with _legacy_ + appended and is not officially supported moving forward. See details as follow. + + Legacy boot flow: + socfpga_agilex_defconfig -> socfpga_agilex_legacy_defconfig + socfpga_n5x_defconfig -> socfpga_n5x_legacy_defconfig + socfpga_stratix10_defconfig -> socfpga_stratix10_legacy_defconfig + + Official boot flow: + socfpga_agilex_atf_defconfig -> socfpga_agilex_defconfig + socfpga_n5x_atf_defconfig -> socfpga_n5x_defconfig + socfpga_stratix10_atf_defconfig -> socfpga_stratix10_defconfig + +10. FPGA full reconfig flow for SoC64 devices +--------------------------------------------------------------------- + Bridges should be disabled before running any FPGA reconfiguration, + this ensures that all outstanding traffic between MPFE to bridge and + FPGA to bridge are completed. + + Bridges should be enabled after FPGA is successfully programmed + and entered user mode. + + Legacy and official boot flow: + If you are running fpga load command in U-Boot console, you are required + to run below steps to gracefully shutdown the bridges before running FPGA + reconfiguration: + 1. bridge disable command + 2. fpga load command + 3. bridge enable command after FPGA is successfully programmed + + If you are running bootm to program FPGA with bitstream loading from + FIT, you are required to run below steps before running bootm command. + 1. bridge disable command (can be done in U-Boot script) + 2. bootm, the bridge would be enabled automatically once FPGA is + is successfully programmed. -- 2.25.1
