This article describes how to create an SD card image used to boot the HPS (Hard Processor System) side of Altera® ( Intel® ) SoC FPGA device.
Introduction
The instructions for creating an SD card image for booting the HPS are provided in the Golden System Reference Design (GSRD) User Manuals atRocketboards.org . The instructions assume that you are working under a Linux OS environment. (see link below).
Reference: Creating and Updating SD Card | Rocketboards.org
This article introduces the same contents as the above page, as well as how to edit SD card images under Windows for users using Windows OS on their development machines.
1. Boot SD card image requirements
The SD card image structure applied to GSRD (Linux Reference) is shown below. The boot SD card image must have the same partition structure as shown below.
Figure 1. Structure of SD card image for boot (SoC EDS v18.1 or earlier)
Point: In the reference image, a partition with EXT FS applied to Partition 2 is provided, but this is not necessary when using an OS other than Linux or Baremetal (OS-less).
As a requirement, an image that meets the following conditions can be used for booting.
- FAT FS is applied to the primary partition (Partition 1).
- Include a custom partition (Type=A2) for storing the boot loader. Placement is OK as long as it is Partition 2 or later (partition number is not required).
Point: The configuration of files required for booting also depends on the implementation of the boot loader and the target OS to be booted. The configuration of files included in the SD card image has changed because of the newer version of U-Boot in GSRD that supports the recent tool version.
The latest file structure is shown in Figure 2. The parts in red are the differences from the previous version.
Figure 2. Structure of SD card image for boot (SoC EDS 20.1 or later)
For the latest information on how to create files to be included in the SD card image, please refer to the following page.
Reference: Building Bootloader | Documentation | RocketBoards.org
Note: For more information on SD card requirements for booting, please refer to the HPS Technical Reference Manual for each device family for details. It can be found in the "Appendix A: Booting and Configuration" section.
2. How to create an SD card image
This section describes how to edit the SD card image for each OS environment of the development machine.
2-1. Support for Linux OS Environment
If you are using a Linux OS environment, you can create and update SD card images, and if it is difficult to prepare a dedicated Linux OS machine, you can use a virtual environment with a Linux guest OS installed under a Windows host OS environment.
2-1-1. Creating SD card image
Python scripts named make_sdimage.py or make_sdimage_p3.py are available for creating SD card images. You can find instructions on how to obtain this script at Creating and Updating SD Card | Rocketboards.org, so please obtain this script file first.
The same file is also attached to this article (download from the link at the end of the page), just in case.
Key point: make_sdimage.py and make_sdimage_p3.py should be selected according to the Python version available in the Linux environment you are working in. The "make_sdimage.py" in the text should be replaced with "make_sdimage_p3.py" as appropriate.
Note:
make_sdimage.py requires Python 2.x (argparse-enabled version (2.7 or later)). Make sure it is installed beforehand.
NOTES:
The latest version is make_sdimage_p3.py. This is only available in Python 3.x environment.
The following is a help page for make_sdimage.py. You need to prepare the files to be included in the image in advance, but basically you can create an SD card image just by running make_sdimage.py.
usage: make_sdimage.py [-h] [-P PART_ARGS] [-s SIZE] [-n IMAGE_NAME] [-f]
Creates an SD card image for Altera's SoCFPGA SoC's
optional arguments:
-h, --help show this help message and exit
-P PART_ARGS specifies a partition. May be used multiple times. file[,file
,...],num=<part_num>,format=<vfat|fat32|ext[2-4]|xfs|raw>,
size=<num[K|M|G]>[,type=ID]
-s SIZE specifies the size of the image. Units K|M|G can be used.
-n IMAGE_NAME specifies the name of the image.
-f deletes the image file if exists
Usage: PROG [-h] -P <partition info> [-P ...] -P
As an example, when creating an image for GSRD (Linux reference), the following command line options are specified (three -P options build three partitions)
$ sudo ~/make_sdimage.py \
-f \
-P preloader-mkpimage.bin,u-boot.img,num=3,format=raw,size=10M,type=A2 \
-P rootfs/*,num=2,format=ext3,size=3400M \
-P zImage,u-boot.scr,soc_system.rbf,socfpga.dtb,num=1,format=vfat,size=256M \
-s 3700M \
-n sd_card_image_cyclone5.bin
The file path following sudo must be changed according to the location of make_sdimage.py (the above is an example where make_sdimage.py is stored directly under the home directory (~/)).
When determining the image size (-s option), note that there is a difference between the capacity listed on the SD card product and the size that can actually be used. For example, if a 4GB SD card is to be used, it must be 3700MB in size, as shown in the example above, in order to be able to write to it.
2-1-2. Writing/Updating SD Card Images
In a Linux OS environment, the dd command can be used to write to the SD card.
$ sudo dd if=<input file name> of=<output device file> [bs=<block size>] [seek=<block>]
Note :
<output device file> specifies the device file for the SD card, but be aware that the file name may vary depending on the Linxu distribution and PC environment.
Be sure to specify the correct device file for the SD card to be written by checking the list of files under /dev before and after the SD card is inserted. The worst case scenario may be that Linux development machine cannot be booted.
■ Write the entire SD card image (Note that the "*" in "of=/dev/sd*" may differ depending on the environment)
$ sudo dd if=simple_sdimage_512MB.img of=/dev/sde bs=1M
■ Update the boot loader on the SD card for boot (Note that the "3" in of=/dev/sd*3 is the partition number)
For Cyclone® V SoC / Arria® V SoC:
$ sudo dd if=preloader-mkpimage.bin of=/dev/sde3 bs=64k seek=0
$ sudo dd if=u-boot.img of=/dev/sde3 bs=64k seek=4
For Arria® 10 SoC:
$ sudo dd if=uboot_w_dtb-mkpimage.bin of=/dev/sde3 bs=64k seek=0
■ Update other partitions (FAT FS, EXT FS)
Except for the custom partition (Type=A2), the Linux OS can recognize the file system just like a normal SD card. In recent Linux distribution environments, each partition is automatically mounted when the SD card is inserted, and can be edited directly from the terminal or file manipulation applications (software similar to Windows Explorer).
2-2. Working in Windows OS environment
The procedure for creating an SD card image from scratch is not supported under the Windows host OS environment. It is possible to write an existing image file to the SD card as a base and then customize it as necessary.
Note:
Does not support editing the Linux file system (EXT FS). If you wish to edit the EXT FS, you will need to do so in a Linux OS environment.
Please refer to the following procedure.
2-2-1. Obtain the base SD card image
The SD card image for the manufacturer's Development Kit can be downloaded from the Reference Design (GSRD) Release Notes page on Rocketboards.org. Reference design images for boards with other SoC FPGAs are also acceptable.
Reference: GSRD 18.1 Release Notes - Release Contents | Rocketboards.org
The reference design images are large due to the inclusion of the Linux file system, and will take a very long time to download and write. If your target OS is not Linux, the simple SD card image attached to this article is recommended.
2-2-2. Writing the Base SD Card Image
Use Win32 Disk Imager to write the image under Windows environment. Refer to the image below to specify the image file and then execute Write.
Figure 3: How to use the Win32 Disk Imager tool (writing an image)
Note: The drive letter for the SD card may vary depending on your PC environment.
When the Write Successful popup appears, the writing is complete. Click the OK button to finish.
The following article provides more detailed instructions and troubleshooting. Reference: What to do if writing an SD card image fails in Windows® 10:
2-2-3. Editing the A2 partition (rewriting the boot loader)
The SD Card Boot Utility (alt-boot-disk-util.exe) included in the SoC FPGA Embedded Development Suite (SoC EDS) can be used to rewrite the boot loader image on a custom partition (type = 0xA2).
Execute the following command on the Embedded Command Shell to write the boot loader image for the target board to the SD card.
Note: The SD Card Boot Utility can be used to write the boot loader image:
SoC EDS v18.1 or earlier is required to use the SD Card Boot Utility.
If you are using a version newer than SoC EDS v18.1, please also see the following article.
Reference: Rewrite U-Boot on SD card for boot in Windows environment (SoC EDS v20.1~)
■ Rewriting the boot loader for Arria® 10 SoC
$ alt-boot-disk-util.exe -B <U-Boot Image> -a write -d <SD Card Drive Letter>
Execution example:
■ Rewriting boot loader for Cyclone® V SoC / Arria® V SoC
$ alt-boot-disk-util.exe -p <Preloader Image> -b <U-Boot Image> -a write -d <SD Card Drive Letter>
Execution example:
Please refer to the help file "alt-boot-disk-util.exe --help" and the SoC EDS User Guide for more information.
Reference: Intel® SoC FPGA Embedded Development Suite (SoC EDS) User Guide
2-2-4. Editing the FAT partition (rewriting the U-Boot script /OS/ user app)
The contents of the FAT partition can be edited from Windows Explorer.
If the image is based on the reference design, the following files are stored, so replace the files as necessary.
-
- U-Boot script (u-boot.scr)
- Linux kernel image (zImage)
- Linux device tree (.dtb)
- FPGA Configuration Binary (.rbf) / FIT image (.itb)
- Linux boot options file (extlinux/extlinux.conf)
Note:
Linux device tree and FPGA configuration binary/FIT image are board-dependent data and must be replaced.
Please refer to the following contents for information on editing U-Boot scripts.
Reference: How to Edit U-Boot Scripts
2-2-5 Creating SD Card Image
By using the Read function of Win32 Disk Imager, it is possible to save the edited SD card contents in an image file. Refer to the image below to specify the Image File and then execute Read.
Figure 4] How to use the Win32 Disk Imager tool (Read Image)
Note: The drive letter for the SD card may vary depending on your PC environment.
When the Read Successful popup appears, the creation is complete. Click the OK button to finish.
3. Simple SD card image
For users whose target OS is not Linux, we have prepared an SD card image that does not use EXT FS. Based on this image, all partitions can be edited in the Windows OS environment.
Attached file: simple_sdimage_512MB.tgz is available for download.
The Simple SD Card Image is created with the following structure. Please use it as a base image when creating your original SD card image.
Figure 5. Simple SD Card Image Structure
Note:
When using this image to boot a board with Arria® 10 SoC, delete the u-boot.scr file stored beforehand in the FAT partition ( because the commands included in the script are written for Cyclone® V SoC / Arria® V SoC).
Conclusion
There are few problems for evaluation boards because SD card images are provided by each board vendor, but once you create your original board, there are many cases where you will have trouble creating a boot image. Also, there are many cases where you want to create an original image even at the evaluation stage.
I hope the information in this article will be useful when you have trouble creating an original image.
Finally, this time we have introduced how to make a boot SD card, but we have also prepared an article on booting from QSPI Flash. For QSPI Flash boot, please refer to the following article.
Reference: QSPI Bare Metal App Booting of SoC FPGAs (Cyclone® V SoC / Arria® V SoC)
Reference: QSPI Bare Metal App Boot for SoC FPGAs (Arria® 10 SoC FPGAs)