NOTES:
This article covers SoC Embedded Design Suite (hereafter SoC EDS) version v18.1 and earlier.
Starting with v19.1 Standard Edition / v19.3 Pro Edition of SoC EDS, the bootloader generation flow has changed and the Preloader Generator is no longer used.
Please refer to the following page for the boot loader generation flow for v19.1 Standard / v19.3 Pro Edition and later.
- Boot Loader Generation Flow for SoC EDS v19.1 std / v19.3 pro and later (Cyclone® V SoC / Arria® V SoC) - (In Japanese)
- Bootloader generation flow for SoC EDS v19.1 std / v19.3 pro or later (Arria®10 SoC) - (In Japanese)
- Building Bootloader for Cyclone V and Arria 10
1. introduction
This article describes how to use the Preloader Support Package Generator (also known as bsp-editor) included with SoC EDS version v18.1 or earlier.
1-1. requirements
To perform the various procedures described in this article, the following development environment must be installed on the host PC.
- Quartus® Prime v18.1
- SoC EDS v18.1
The instructions in this article assume that you are using version v18.1 and have installed the tools in the following locations, which is the default installation path.
Please refer to the screen captures used in this article for the installation paths of the tools as needed.
- Installation path for Quartus® Prime: C:¥intelFPGA¥18.1¥quartus
- Installation path for SoC EDS: C:¥intelFPGA¥18.1¥embedded
1-2. Related Documents
This article is based on the following documents and websites. Please also refer to these documents and websites.
Reference: SoC Embedded Design Suite User Guide
Reference: Cyclone V Device Handbook
Reference: RocketBoards.org (SoC FPGA community portal site)
1-3. What is Preloader?
Preloader is a boot loader based on the U-boot second program loader (hereinafter referred to as u-boot spl), customized for SoC FPGAs.
The Preloader is responsible for:
- Configuration of HPS pin multiplexing
- HPS IOCSR configuration
- Configuring HPS PLLs and clocks
- Unreset HPS peripherals
- Initialize SDRAM (calibration, etc.)
- Deployment of next-stage boot image to SDRAM
As described above, the Preloader provides the ability to initialize the HPS block and load u-boot and OS into SDRAM.
As described later in this article, the Preloader is automatically generated by using a handoff file that is automatically generated at design time by Quartus® / Platform Designer (formerly Qsys). Therefore, the HPS block can reflect the settings made in Quartus® / Platform Designer without the need for users to build initialization software.
Figure 1-1. Example of Platform Designer HPS configuration
1-4. Boot sequence
The general boot sequence for SoC devices is shown below.
Each stage is responsible for loading the boot image for the next stage, which in turn loads and executes the boot images.
Note that the boot sequence presented below is only an example and other configurations are possible.
The roles of each stage of a typical boot sequence are shown below:
(1) BootROM
The Arm processor inside the HPS jumps to the device's internal BootROM when reset is released and starts executing software; the BootROM performs only the minimum initialization required to load the Preloader from the BSEL and CSEL pin settings, The BootROM software cannot be rewritten by the user.
(2) Preloader
As mentioned above, Preloader is a boot loader to initialize the HPS part.
Preloader executes the initialization of the HPS part and SDRAM, and expands the Bootloader of the next stage to SDRAM and passes the process.
(3) Bootloader
The bootloader in this stage is generally deployed as the Operating System (hereinafter referred to as "OS") specific loader. u-boot provided as open source is used as the Linux bootloader in the case of Linux.
(4) OS / Application
The OS executes necessary processes and starts application execution at boot time.
Please refer to the following document for details on the boot sequence.
Reference: Booting and Configuration
Figure 1-2. SoC General Boot Sequence
2. How to use the Preloader Generator
This section describes the procedures and options for using the Preloader Generator.
2-1. Starting the Embedded Command Shell
Start the Embedded Command Shell that comes with SoC EDS.
Execute the startup script stored under the SoC EDS installation folder from the Windows Start menu or Windows Explorer.
Figure 2-1. Launching Embedded Command Shell
2-2. Start bsp-editor (Preloader Generator)
Type "bsp-editor" in Embedded Command Shell to start bsp-editor GUI.
Figure 2-2. Launching bsp-editor
2-3. Create a new project
Select [File] → [New HPS BSP...] to create a new project.
Figure 2-3. Creating a new project
2-4. Specifying the handoff file
Specify the handoff file that will be automatically generated when the project is compiled in Quartus® / Platform Designer. In this article, we will use the handoff file stored in the reference design that comes with SoC EDS.
| <SoC EDS Install DIR>¥embedded¥examples¥hardware¥cv_soc_devkit_ghrd¥hps_isw_handoff¥soc_system_hps_0 |
Figure 2-4. Specifying the handoff file
Make sure that Preloader is specified in the "Operating System:" field and default is specified in the "Version:" field.
Specify the location where the bsp project will be generated in BSP target directory.
By default, "<Quartus Project DIR>¥software¥spl_bsp" is specified, but you can specify any directory by unchecking use default locations.
2-5. Setting of preloader user options
Set various user options to be given to Preloader when generating. Settings are broadly divided into "Common" and "Advanced". Change the settings for each as necessary.
Hover the mouse over each setting to see an explanation of the setting, so please check that as well. Each setting will be explained below.
Figure 2-5. User Option Settings
2-5-1. Common Option Settings
In the Common Option settings, basic options for the Preloader are configured. The settings are shown below.
| Major item | Sub-item | Summary of settings |
| spl | PRELOADER_TGZ | Specifies an archive of Preloader source files. The specified archive file is extracted and used. Basically, no modification is required. |
| CROSS_COMPILE | Specifies the cross compiler used to build the preloader. | |
| spl.boot | BOOT_FROM_QSPI | Check this box if the boot image following Preloader is to be loaded from QSPI flash. |
| BOOT_FROM_SDMMC | Check this box if the boot image following the Preloader is to be loaded from an SD card. | |
| BOOT_FROM_NAND | Check this box if the boot image following the Preloader is to be loaded from NAND flash. | |
| BOOT_FROM_RAM | Check this box if the boot image following the Preloader is to be loaded from RAM. | |
| * Specify only one of the above BOOT_FROM_XXX settings (do not check more than one). | ||
| QSPI_NEXT_BOOT_IMAGE | Specify the address where the boot image loaded by the preloader is stored when BOOT_FROM_QSPI is enabled. | |
| SDMMC_NEXT_BOOT_IMAGE | When BOOT_FROM_SDMMC is enabled, this specifies the address where the boot image loaded by the preloader is stored. | |
| NAND_NEXT_BOOT_IMAGE | Specify the address where the boot image loaded by the preloader is stored when BOOT_FROM_NAND is enabled. | |
| FAT_SUPPORT | Enables access to the FAT partition on the SD card. This setting is valid only when BOOT_FROM_SDMMC is specified and the FAT partition contains the next stage boot image. | |
| FAT_BOOT_PARTITION | Specifies the number of the FAT partition where the next stage boot image will be stored. This setting is valid only when the FAT_SUPPORT option is specified. | |
| FAT_LOAD_PAYLOAD_NAME | Specifies the file name of the next stage boot image. This setting is valid only when the FAT_SUPPORT option is specified. | |
2-5-2. Advanced Option Setting
The Advanced option setting is used to set advanced functions related to the preloader. In general, there is no need to change these settings, but they can be changed depending on the situation.
Figure 2-6. Advanced Option Settings
| Major Item | Sub-item | Overview |
| spl.reset_assert | - | Specifies whether to release the reset of the corresponding peripheral when the Preloader is executed. If checked, the peripheral will remain in the reset state. |
| spl.warm_reset_handshake | - | Specifies whether or not to use the handshake function with the relevant peripheral during a WarmReset. |
| spl.boot | WATCHDOG_ENABLE | Specifies whether the watchdog timer is used or not. It is recommended to disable it for debugging. |
| CHECKSUM_NEXT_IMAGE | Specifies whether error checking by checksum is performed when loading the next stage boot image. | |
| EXE_ON_FPGA | Enables checks to run the Preloader on FPGA memory again. This option is used when BSEL is specified for FPGA. | |
| FPGA_MAX_SIZE | Specifies the maximum size of .text and .rodata that can be placed in FPGA memory; a build error is returned if the actual code size is larger than this size when the Preloader is built. | |
| FPGA_DATA_BASE | Specifies the base address where .data, .bss, malloc, and stack are placed when the EXE_ON_FPGA option is enabled. | |
| FPGA_DATA_MAX_SIZE | Returns a build error if the actual data (e.g., .data) is larger than this size when the Preloader is built. | |
| STATE_REG_ENABLE | Writes STATE_VALID data to the STATE R register when the Preloader is executed. This indicates that the Preloader has been successfully loaded into BootROM. | |
| BOOTROM_HANDSHAKE_CFGIO | Performs a handshake with BootROM during IOCSR and Pin MUX initialization. If WarmReset occurs when this setting is enabled, the device will be reset by BootROM even if the Preloader has initialized the device. |
|
| WARMRST_SKIP_CFGIO | When this setting is enabled, the Preloader will skip setting IOCSR and Pin MUX. This setting is valid only when BOOTROM_HANDSHAKE_CFGIO is disabled. | |
| SDRAM_SCRUBBING | Perform memory initialization when SDRAM ECC is enabled. | |
| SDRAM_SCRUB_BOOT_REGION_START | Specify the start address of the memory to execute SCRUB. | |
| SDRAM_SCRUB_BOOT_REGION_END | Specify the end address of memory to execute SCRUB. | |
| SDRAM_SCRUB_REMAIN_REGION | Specifies whether to initialize the remaining memory area not specified by the SCRUB option above while loading the next stage boot image. | |
| spl.debug | DEBUG_MEMORY_WRITE | Specifies whether or not to use the option to write debug information to memory, useful for systems where UART is not available. |
| DEBUG_MEMORY_ADDR | Specifies the first address of the memory to write debug information. | |
| DEBUG_MEMORY_SIZE | Specifies the memory size allocated for the memory to write debug information. | |
| SEMIHOSTING | Specifies whether the semi-hosting function is used. Note that this option assumes that the debugger is connected, and is useful for debugging the Preloader on systems where UART is not available. | |
| HARDWARE_DIAGNOSTIC | Performs a simple test of SDRAM memory. At least 1 GB of memory space is required to use this option. | |
| SKIP_SDRAM | Skip initialization and calibration of SDRAM memory when running the Preloader. | |
| spl.performance | SERIAL_SUPPORT | Enables log output using UART. |
2-6. Bsp project generation
After completing the various settings, generate the bsp project. The generated bsp project will contain all the files necessary to generate (build) the Preloader, including *.c, *.h, and Makefile.
These files will be output to the location specified in "BSP target directory" in "2-4. Specifying the handoff files".
Click the "Generate" button in the bottom right of the bsp-editor to generate the project. In this document, the following directories apply.
| <SoC EDS Install DIR>¥embedded¥examples¥hardware¥cv_soc_devkit_ghrd¥software¥spl_bsp |
Figure 2-7. Generating a bsp project
3. How to Generate Preloader
This section describes how to generate a preloader using the bsp project generated in the previous step.
3-1. Launching Embedded Command Shell
Start the Embedded Command Shell. For instructions on how to start it, see "2-1. Starting the Embedded Command Shell" above.
3-2. Move to the bsp project directory
Use the cd command to move to the root directory of the bsp project generated by the Preloader Generator (bsp-editor). The example in this article corresponds to the following directory.
| <SoC EDS Install DIR>¥embedded¥examples¥hardware¥cv_soc_devkit_ghrd¥software¥spl_bsp |
Figure 3-1. Moving to the bsp project directory
3-3. Building the preloader
Execute the "make all" command to generate the Preloader.
Figure 3-2. Build Preloader
After execution, confirm that a binary file named preloader-mkpimage.bin has been generated under "<Quartus Project Top DIR>¥software¥spl_bsp".
This file is a binary with header information for the Preloader referenced by BootROM. This binary file is used to write to the SD card and QSPI flash memory, etc.
Figure 3-3. Generated Preloader binary file
Note:
This article has been tested using Windows® 7 Professional.
If the OS of the host PC is Windows® 10, it has been confirmed that an error may occur in the generation of the preloader. If the error occurs on Windows® 10, please note that you will need to edit the Makefile in the bsp project, which is introduced in the following Ultima Technical Support contents page.
Reference: How to solve the problem when Preloader cannot be built on Windows® 10 - (In Japanese)
3-4. Build u-boot (if necessary)
Execute the "make uboot" command to generate u-boot.
Figure 3-4. Generating u-boot
Execute the above command to generate u-boot.img, which is the u-boot binary image with the header referred to when loaded by Preloader, in the following directory.
| <Quartus Project Top DIR>¥software¥spl_bsp¥uboot-socfpga¥u-boot.img |
Figure 3-5. Generated u-boot image file
4. How to update Preloader / u-boot
This section describes how to write the newly created Preloader binary file created in the previous step to the pre-setup SD card and on-board QSPI Flash memory.
The procedure described in this article is only an example and can be rewritten in other ways.
4-1. Rewriting the Image on the SD Card
The instructions for rewriting the image on the SD card assume that the SD card image published on RocketBoards.org or the SD card image included with the SoC EDS has been written.
If the SD card setup has not been completed, please refer to the Getting Started Guides in the SoC Embedded Design Suite User Guide introduced in "1-2. Related Documents" to proceed with the setup.
The SD card image included with the SoC EDS is saved in the following location:
| <SoC EDS Install DIR>¥embedded¥embeddedsw¥socfpga¥prebuilt_images¥sd_card_linux_boot_image.tar.gz |
SoC EDS v18.1 includes a tool (Boot Disk Utility) to rewrite the contents of the SD card directly from a Windows machine. The Boot Disk Utility allows you to partially rewrite only the Preloader / u-boot data to an SD card that has already been setup with one of the above SD card images.
Note that the Boot Disk Utility requires the Embedded Command Shell to be started with administrator privileges.
To rewrite Preloader / u-boot, use the following command:
- Preloader:
$ alt-boot-disk-util -p preloader-mkpimage.bin -a write -d D
- u-boot:
$ alt-boot-disk-util -b uboot-socfpga/u-boot.img -a write -d D
* The drive letter specified in the -d option of the above command will differ depending on the host PC environment. Please replace it according to your environment.
Figure 4-1. Rewriting the SD card image
For Linux machines, the same process can be achieved by using the dd utility.
Reference: GSRD v14.0 - SD Card - Updating Individual Elements on the SD card
4-2. Rewriting QSPI Flash Memory
For on-board QSPI Flash memory, the HPS Flash Programmer included with the SoC EDS can be used. This tool writes directly to the QSPI Flash memory via JTAG.
Figure 4-2. Flash Writing with the HPS Flash Programmer
Before starting, make sure that the BSEL pin is set to QPSI boot.
| BSEL[2:0] Value | Flash Device |
| 0x0 | Reserved |
| 0x1 | FPGA (HPS-to-FPGA bridge) |
| 0x2 | 1.8 V NAND flash memory |
| 0x3 | 3.3 V NAND flash memory |
| 0x4 | 1.8 V SD/MMC flash memory with external transceiver |
| 0x5 | 3.3 V SD/MMC flash memory with internal transceiver |
| 0x6 | 1.8 V Quad SPI flash memory |
| 0x7 | 3.3 V Quad SPI flash memory |
The commands to rewrite Preloader / u-boot in the HPS Flash Programmer are as follows:
- Preloader:
$ quartus_hps -c 1 -o p preloader-mkpimage.bin
- u-boot:
$ quartus_hps -c 1 -o p -a 0x60000 uboot-socfpga/u-boot.img
Figure 4-3. Writing images using the HPS Flash Programmer
For more information on HPS Flash Programmer, please refer to the following document page.
Reference: SoC Embedded Design Suite User Guide ⇒ 8. Using the HPS Flash Programmer