1. Introduction
This article describes an example of running the bare-metal sample application Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU standalone from the QSPI Flash in the Cyclone® V SoC Development Kit or the Arria® V SoC Development Kit.
This bare-metal sample application is a simple application that displays a "Hello World!" message via UART (no need to download the hardware design (sof file) to the FPGA).
This article covers the following topics:
1. important hardware development artifacts (handoff files)
2. boot flow of an SoC FPGA
3. How to build a bare-metal sample application on DS-5
- Booting DS-5
- Importing Bare Metal Sample Applications
- Build Bare Metal Sample Application
4. How to generate Preloader for QSPI Flash Boot
- What is Preloader?
- How to generate Preloader for QSPI Flash Boot
5. example of standalone execution of bare-metal application from QSPI flash
- How to write Preloader and application image to QSPI flash
- Confirmation of Standalone Execution
Point:
Although this article mainly targets the Cyclone® V SoC FPGA, it also applies to the Arria® V SoC FPGA since the hard processor system (HPS) part is almost identical.
The main development environment used in the description of this article is shown below.
[Table 1-1] Main Environments Used in the Descriptions in this Article
| Item Number | Item | Contents |
|---|---|---|
| 1 | Host PC |
Host PC running Microsoft® Windows® 7 or later This document uses Windwos® 7 Professional to verify the operation. |
| 2 |
Quartus® Prime Development Software (hereinafter referred to as Quartus® Prime) |
This is a tool for developing SoC FPGA hardware. This document uses Quartus® Prime Development Software Standard Edition v18.1. Quartus Prime Standard Edition v18.1 You must install the Device data corresponding to the SoC FPGA on the target board you are using. For information on how to install Quartus Prime, please refer to the following website How to install Quartus® Prime development software and ModelSim® - Altera® FPGA Edition - (In Japanese) |
| 3 | SoC FPGA Embedded Development Suite Standard Edition (hereinafter referred to as SoC EDS) |
This is a tool for developing software for SoC FPGAs. The Arm® Development Studio 5 Altera® SoC FPGA Edition (hereinafter referred to as DS-5) included with SoC EDS can be used to build and debug application software. This document uses SoC EDS Standard Edition v18.1. SoC EDS Standard Edition v18.1 Debugging bare-metal applications using the Altera® FPGA Download Cable II (USB-Blaster II) requires Arm® Development Studio 5 Altera® SoC FPGA Edition (paid version). For information on how to install SoC EDS, please refer to the following website How to install SoC FPGA Embedded Development Suite (SoC EDS) |
| 4 |
Cyclone® V SoC Development Kit or Arria® V SoC Development Kit |
This development kit is used as the target board in this document. Cyclone® V SoC Development Kit Arria® V SoC Development Kit |
| 5 | Bare Metal Sample Applications |
This is a bare-metal sample application used in this document. This bare-metal application is a simple application that displays a "Hello World!" message via UART. To actually check the operation, please obtain the following files along with this document. Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU.tar.gz The description in this document assumes that Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU.tar.gz is stored in C:\Temp It is not necessary to download the hardware design (sof file) to the FPGA when running this bare-metal sample application. |
| 6 | terminal emulation software |
Serial terminal software is required to use this sample. In this document, freeware software called "Tera Term" is used. Download URL of Tera Term In Tera Term, make the following settings for the valid COM port when connecting to the UART on the target board. ・ Baud rate 115200 bps ・ 8-bit data ・ No parity ・ 1 stop bit ・ No flow control |
Point:
This article assumes basic knowledge of Quartus® Prime, SoC EDS, bsp-editor (Preloader Generator), and DS-5.
Reference:
- The following user guides may be helpful for basic operations related to booting SoC FPGAs.
HPS SoC Boot Guide - Cyclone V SoC Development Kit AN 709
- For QSPI boot information for SoC FPGAs, refer to the following pages
GSRD v13.1 - Booting from QSPI
- For basic operation related to debugging bare metal SoC FPGAs, please refer to the following user guides.
SoC Beginner's Guide - Bare Metal Application Debugging with DS-5
- For information for SoC FPGA bare-metal developers, please refer to the following pages
SoC FPGA Bare-metal Developer Center
2. Preliminary preparation
This article uses the Cyclone® V SoC Development Kit as the target board.
This section describes the board configuration and FPGA design files required to use the above board.
2-1. Board configuration
2-1-1. Board layout
The layout diagram of the Cyclone® V SoC Development Kit is shown below.
[Figure 2-1] Cyclone® V SoC Development Kit Layout
2-1-2. Power supply and cable connection
Connect the AC adapter and various cables as shown below.
- Connect the power supply (AC adapter) to the DC input (J22).
- Connect the host PC to the onboard USB-Blaster II connector (J37) with the Mini USB cable.
- Connect the host PC to the UART connector (J7) with the Mini USB cable.
2-1-3. BSEL (BOOTSEL) pin settings
Make sure J28 - J30 (BSEL pins) are set as shown below.
This setting makes the HPS QSPI boot.
[Table 2-1] BSEL pin settings
| Board Reference | Signal Name | Setting |
|---|---|---|
| J28 | BOOTSEL0 | Left |
| J29 | BOOTSEL1 | Left |
| J30 | BOOTSEL2 | Left |
[Figure 2-2] BSEL pin setting
Reference:
- For information on the Cyclone® V SoC Development Kit, refer to the following documents
Cyclone V SoC Development Kit User Guide
Cyclone V SoC FPGA Development Board Reference Manual
- For information on the Arria® V SoC Development Kit, please refer to the following documents
Arria V SoC FPGA Development Kit User Guide
Arria V SoC Development Board Reference Manual
2-2. Hardware design file
To generate the Preloader described in "5. How to Generate Preloader for QSPI Flash Boot", you need the "handoff file" generated during hardware development.
The instructions in this article use the hardware design that comes with the SoC EDS installed on C:\intelFPGA\18.1.
2-2-1. Where to store the hardware design files
When SoC EDS is installed, the files are stored in the following locations by default.
(1) Cyclone® V SoC Development Kit
C:\intelFPGA\18.1\embedded\examples\hardware\cv_soc_devkit_ghrd
(2) Arria® V SoC Development Kit
C:\intelFPGA\18.1\embedded\examples\hardware\av_soc_devkit_ghrd
Point:
This article In the description we use the SoC EDS is installed in C:\intelFPGA\18.1.
2-2-2. Important products in hardware development (handoff files)
In developing and debugging bare-metal applications, the final folders and files generated during hardware development are used.
These folders and files are called "handoff files.
If you used the development kit reference design, you will find the hardware and software handoff files generated by the tool in the <Quartus® Prime project>\hps_isw_handoff\soc_system_hps_0 folder, if generated correctly.
These files will be used in section, "5-2. Preloader Generation Procedure ". Remember that the bsp-editor (Preloader Generator) tool used to generate the Preloader specifies the path to this hps_isw_handoff\soc_system_hps_0 folder.
3. Boot flow of SoC FPGA
First of all, the boot flow of SoC FPGA is explained.
Reference:
For more information about the boot flow, the following user guide is helpful.
HPS SoC Boot Guide - Cyclone V SoC Development Kit AN 709
As shown in the figure below, there are multiple stages in the SoC FPGA boot flow.
In the case of bare-metal applications, the most common method is to boot the bare-metal application directly from the Preloader, shown in the red box below.
This article also describes the mechanism to achieve this boot flow.
[Figure 3-1] General Boot Flow
[Figure] 3-2 Additional Boot Flow
- BootROM
BootROM is the boot code burned into the SoC FPGA's internal on-chip ROM (cannot be changed by the user).
- Preloader
Based on the information in the handoff file, this executes necessary processes for operation such as initialization of HPS IO and SDRAM controllers.
- Boot Loader
User boot loader code (e.g., U-Boot). Depends on the application and OS.
- Bare Metal Application
Applications that do not use an OS are called bare-metal applications; you can use the SoC FPGA hardware library (HWLib) to create bare-metal applications that read and write directly to the hardware.
4. How to build a bare-metal sample application on the DS-5
This chapter describes how to import a bare-metal sample application project into DS-5 and build it.
4-1. Starting DS-5
Start Arm® Development Studio 5 Altera® SoC FPGA Edition (DS-5) included in SoC EDS.
To automatically configure various environment settings for SoC EDS, DS-5 should be started from the following Embedded Command Shell.
4-1-1. Launching Embedded Command Shell
Start Embedded Command Shell by executing the startup script stored in the Windows Start menu or in the SoC EDS installation folder (embedded folder).
[Figure 4-1] Launching Embedded Command Shell
4-1-2. Starting DS-5
(1)
When the Embedded Command Shell window opens as shown below, enter the command eclipse & to start DS-5.
[Figure 4-2] Starting DS-5
(2)
You will be prompted to enter a workspace folder. Select or create a unique workspace for your software project.
Specify the path and click [OK] (In this example, the workspace is
C:\Work\DS-5_Workspace. If the folder does not exist, it will be created automatically).
[Figure 4-3] Specifying the workspace for DS-5
(3)
If the DS-5 Welcome Screen appears, click [Close] (marked with an X).
The DS-5 Welcome Screen can be used to access documents, tutorials and videos.
[Figure 4-4] DS-5 Welcome Screen
NOTES:
At this point, if you get the prompt "Toolkit is not selected", click "Notify me later" to proceed. Also, if the "WindowsSecurity Important Warning" prompt appears, click [Allow Access(A)].
4-2. Importing bare-metal sample application
In this example, we will import the bare-metal sample application Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU, which we have previously downloaded, into the DS-5.
This bare-metal application simply displays a "Hello World!" message via UART.
(1)
Select "File" => "Import..." from the DS-5 menu.
(2)
Select "General" ⇒ "Existing Projects into Workspace" and click [Next].
[Figure 4-5] Importing an existing project
(3)
Select the "Select archive file:" option, click the "Browse..." button, select
Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU.tar.gz, and then click the "Finish" button.
Point:
This article assumes that Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU.tar.gz is stored in C:\Temp.
[Figure 4-6] Selecting a Sample Application
(4)
The imported bare-metal sample application project Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU is added to the Project Explorer panel on the left side of the DS-5 screen, and Expand HardwareLib-Unhosted-CV-GNU to see the various files contained in the project.
[Figure 4-7] Project added by import
4-3. Build bare-metal sample application
Next, we will build the imported bare metal sample application project so that it can be executed.
4-3-1. Build the Project
Highlight the DS-5 project (in this example, Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU), right-click and execute "Build Project".
[Figure 4-8] Build Project
In the bare-metal sample application project Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU used in this article, when the build is complete according to the instructions in the Makefile, the hello-mkimage.bin file generated from the bare-metal application hello.bin file with the mkimage header added, as explained in the next section, "4-3-2. Adding the mkimage Header". This is the bare-metal application image that will be loaded by the Preloader.
Write this application image and the Preloader described in "5. How to Generate Preloader for QSPI Flash Boot" to the QSPI flash.
[Figure 4-9] Generated bare-metal application image hello-mkimage.bin
4-3-2. Adding mkimage header
The next stage boot image file to be loaded and executed from the Preloader must have the mkimage header information added using the U-Boot utility tool mkimage.
Preloader will verify the headers appended to the boot image before loading the next stage's boot image.
The bare-metal sample application project Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU used in this article description automatically adds the mkimage header to the bare-metal application as instructed in the Makefile Normally, from the Embedded Command Shell, you would enter a command similar to the following example to add the mkimage header information to the binary file.
NOTES:
The above command example assumes that the application start address was created from 0x100040. The application start address is defined in ORIGIN in the linker script file (.ld).
5. How to generate Preloader for QSPI Flash Boot
This chapter describes the procedure for generating the Preloader needed to boot from QSPI flash.
5-1. What is a 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 role of the Preloader is as follows:
- Configuring HPS pin multiplexing
- Configuring HPS IOCSRs
- Configuring HPS PLLs and clocks
- Unreset HPS peripherals
- Initialize SDRAM (calibration, etc.)
- Next stage program deployment/jump to SDRAM
- The Preloader is automatically generated by using the handoff file automatically generated during design in Quartus® Prime / Platform Designer. Therefore, the HPS block can reflect the settings made in Quartus® Prime / Platform Designer without the need for the user to build initialization software.
- In order to run a custom board equipped with the user's SoC FPGA, be sure to generate this Preloader first.
5.2. Preloader generation procedure
The procedure for generating a Preloader is described below.
Reference:
For a more detailed explanation of how to generate a preloader, please refer to the following document.
How to Use Preloader Generator
5-2-1. Starting Embedded Command Shell
Follow the same procedure as described in section "4-4-1. Starting Embedded Command Shell".
Execute the startup script stored in the Windows Start menu or in the SoC EDS installation folder (embedded folder) to start Embedded Command Shell.
5-2-2. Starting bsp-editor (Preloader Generator)
When the Embedded Command Shell window opens as shown below, enter the command bsp-editor to launch the bsp-editor (Preloader Generator) GUI.
[Figure 5-1] Launching bsp-editor (Preloader Generator)
5-2-3. Creating a new bsp project
After the GUI of bsp-editor (Preloader Generator) is launched as shown in the figure, select
"File" ⇒ "New HPS BSP..." from the menu to create a new project.
NOTES:
For versions prior to SoC EDS v15.0 , select "File" ⇒ "New BSP...".
[Figure 5-2] Creating a new bsp project
5-2-4. Specifying a handoff file
(1)
Specify the handoff file folder path <Quartus® Prime project>\hps_isw_handoff\soc_system_hps_0 generated by hardware development.
Press [...] next to Preloader settings directory: to specify the folder as shown.
Point:
This article uses the hardware design that came with the SoC EDS installed in C:\intelFPGA\18.1, so the path shown below is set up.
- For the Cyclone® V SoC development kit:
C:\intelFPGA\18.1\embedded\examples\hardware\cv_soc_devkit_ghrd\hps_isw_handoff\
soc_system_hps_0
- For the Arria® V SoC development kit:
C:\intelFPGA\18.1\embedded\examples\hardware\av_soc_devkit_ghrd\hps_isw_handoff\
ghrd_5astfd5k3_hps_0
(2)
After all specifications are complete, click [OK].
[Figure 5-3] Specifying the handoff file
5-2-5. Setting the Preloader user options (Common ⇒ spl ⇒ boot)
Common ⇒ spl ⇒ boot specifies the settings for loading the boot image following Preloader from QSPI and the storage address of the boot image to be loaded by Preloader.
(1)
Check the option BOOT_FROM_QSPI. This setting loads the boot image following the Preloader from QSPI.
(2)
Uncheck the other boot options (BOOT_FROM_RAM, BOOT_FROM_SDMMC, BOOT_FROM_NAND).
NOTES:
Check only one of the BOOT memory selections (do not check more than one).
(3)
Check that QSPI_NEXT_BOOT_IMAGE = 0x60000. This is the address where the boot image (bare-metal application image) must be stored. The Preloader loads the boot image stored at this address.
[Figure 5-4] Preloader user options (Common ⇒ spl ⇒ boot)
5-2-6. Setting the Preloader user options (Advanced ⇒ spl ⇒ boot)
Advanced ⇒ spl ⇒ boot allows you to disable the watchdog timer and other settings related to boot behavior.
(1)
Uncheck the option WATCHDOG_ENABLE. This is because the bare-metal application does not kick the watchdog timer.
NOTES:
If you use a watchdog timer in your bare-metal application, please add program code to ensure that the watchdog timer works properly.
(2)
Check the options SDRAM_SCRUBBING and SDRAM_SCRUB_REMAIN_REGION.
This will zero-clear the SDRAM and prevent ECC errors from occurring during bare-metal program execution.
[Figure 5-5] Preloader user options (Advanced ⇒ spl ⇒ boot)
5-2-7. Setting the Preloader User Options (Advanced ⇒ spl ⇒ debug)
Advanced ⇒ spl ⇒ debug allows you to configure debugging-related settings, such as whether or not the Semihosting function of DS-5 is supported.
If you want to boot bare-metal applications standalone, turn off SEMIHOSTING checkbox.
To debug the Preloader using the Semihosting feature of Arm® Development Studio 5 Altera® SoC FPGA Edition, turn on the SEMIHOSTING checkbox.
NOTES:
If you want to do standalone booting without using DS-5, be sure to turn off SEMIHOSTING checkbox.
[Figure 5-6] Preloader user options (Advanced ⇒ spl ⇒ debug)
5-2-8. Generate bsp project (Generate)
Click the Generate button at the bottom right to generate a bsp project.
The generated bsp project will contain *.c, *.h, Makefile and other files necessary to generate (build) Preloader.
These files will be generated in the location specified in the BSP target directory in section, "5-2-4. Specifying Handoff Files" (in the example, <Quartus® Prime project>\software\spl_bsp).
After confirming the completion of generation, click the [Exit] button to exit bsp-editor (Preloader Generator).
[Figure 5-7] bsp project generation
5-2-9. Building the Preloader
(1)
Move the current directory of Embedded Command Shell to the directory of the bsp project created by bsp-editor (Preloader Generator).
Enter the following command from Embedded Command Shell.
Point:
This article uses the hardware design that came with the SoC EDS installed in C:\intelFPGA\18.1, so change to the following directory.
- For the Cyclone® V SoC development kit:
C:\intelFPGA\18.1\embedded\examples\hardware\cv_soc_devkit_ghrd\software\spl_bsp
- For the Arria® V SoC development kit:
C:\intelFPGA\18.1\embedded\examples\hardware\v_soc_devkit_ghrd\software\spl_bsp
[Figure 5-8] Go to the bsp project directory
(2)
Execute make all command to generate Preloader.
Confirm that preloader-mkpimage.bin is generated by ls command. This file is a binary file with header information for the Preloader referenced by BootROM, and is used to write to the QSPI flash.
[Figure 5-9] Execute the "make all" command
Note:
An error has been confirmed in the generation of the preloader if the OS of the host PC is Windows® 10.
Error Description
This problem occurs when generating a preloader using the SoC EDS tool.
After creating a new HPS and BSP configuration file, the make command fails as follows.
tar zxf /cygdrive/c/intelFPGA/18.0/embedded/host_tools/altera/preloader/uboot-socfpga.tar.gz
tar: Error opening archive: Failed to open '/cygdrive/c/intelFPGA/18.0/embedded/host_tools/altera/preloader/uboot-socfpga.tar.gz'
make: *** [uboot-socfpga/.untar] Error 1
If the error occurs on Windows® 10, please note that the measures described in the following reference information site are required.
Reference: [Reference information site]
Unable to make preloader in Windows 10 | Altera Community
What to do if Preloader fails to build on Windows® 10
6. Example of running a bare-metal application standalone from QSPI Flash
This chapter describes the steps required to enable bare-metal applications to run standalone from QSPI Flash.
6-1. Layout of the qspi flash
The following figure details the QSPI flash layout for the Cyclone® V SoC Development Kit.
Items of note in the diagram are as follows.
- The instructions in this article write preloader-mkpimage.bin to Preloader image 0 (at location 0x0).
- The instructions in this article write the bare-metal application binary image hello-mkimage.bin in the U-Boot image area (at location 0x60000), which is the next boot image.
[Figure 6-1] Layout of QSPI Flash
6-2. Checking the BSEL (BOOTSEL) Pin Settings
Confirm that the BSEL pins of J28 to J30 are set to QSPI boot according to "2-1-3. BSEL (BOOTSEL) Pin Settings".
6-3. How to write Preloader and Application Image to QSPI Flash
To write to the QSPI flash, use the HPS flash programmer utility.
The HPS Flash Programmer can erase, blank check, program, verify, and inspect the flash. The utility accepts binary files with the required ".bin" extension.
The following is the command line syntax for the HPS flash programmer
quartus_hps <options> <file.bin>
Execute the following command from the Embedded Command Shell to write the Preloader and bare-metal application image to the QSPI flash:
[Figure 6-2] Example of writing the Preloader to QSPI Flash
[Figure 6-3] Example of writing a bare-metal application image to QSPI flash
6-4. Confirmation of standalone execution
Reset the HPS by turning the board power back on or by pressing the COLD reset button (S7).
The board will boot, a Preloader message will appear on the PC serial terminal, and "Hello World!
[Figure 6-4] Booting from QSPI Flash
Reference:
For more information on the SoC EDS, DS-5, Preloader Generator, and HPS Flash Programmer Utility, see the following user guide.
Altera® SoC FPGA Embedded Development Suite User Guide
Documentation/Sample Projects
📕 Documents
SoCFPGA_Baremetal_QSPI_Boot_CV_AV_v181_r1.pdf - (In Japanese)
Instructional Material for Cyclone® V / Arria® V SoC Development Kit ver18.1 (rev.1)
📦 Sample Projects
Altera-SoCFPGA-HardwareLib-Unhosted-CV-GNU.tar.gz
Bare Metal Sample Application