Introduction

The Arrow SoCKit board can boot from an SD card or from the onboard QSPI. The GSRD uses the SD card for booting because it is more convenient for the user.

This page presents the layout of the SD card image used by the GSRD, together with the instructions on how to re-create the SD card image, and also how to update individual elements on the SD card.

Boot Flow

See HPS Boot Flow.

SD Card Layout

The picture below presents the layout of the SD card that is used by the GSRD:

The following table summarizes the information that is stored on the SD card and how each file is generated:

Location	File System	File Name	Description	Source of File
Partition 1	FAT32	soc_system.dtb	Device Tree Blob file	GHRD build with sopc2dts utility
^	^	soc_system.rbf	Compressed FPGA configuration file	GHRD build, convert .sof to .rbf
^	^	u-boot.scr	U-boot script for configuring FPGA	GHRD build, boot.script and mkimage utility
^	^	zImage	Compressed Linux kernel image file	Generated by Yocto with bitbake virtual/kernel
Partition 2	EXT3	various	Linux root filesystem	Generated by Yocto with bitbake sockit-gsrd-console-image
Partition 3	A2 raw	preloader-mkpimage.bin	Preloader image	Generated with SoCEDS and ARM Development Studio BSP Editor based on Quartus handoff information
^	^	u-boot-sockit.img	U-boot image	Generated by Yocto with bitbake virtual/bootloader

The MBR (Master Boot Record) contains descriptions of the partitions on the card, including their type, location and length.

Partition 3 is a custom partition with type=0xa2. It is required by the boot ROM, which will identify it from the MBR and load the Preloader from the beginning of it.

Note that since the MBR describes the partitions, the order of partitions and their locations is not actually relevant. You could have a different order and/or gaps between them and the boot will still be successful.

Creating SD Card Image Using Provided Script

This section presents details on how to create the GSRD bootable SD card image, similar to the SD card image that is provided as part of the precompiled binaries package.

This release of the GSRD includes a Python script that can be used to create a bootable SD card image from the items mentioned in the table above. The script is named make_sdimage.py and is available from here.

The script requires the argparse module, which is part of Python 2.7, but not included with previous versions. If you are using a Python version older than 2.7 you will need to obtain the argparse module separately.

For example, the following command was executed on a CentOS6.5 machine with Python 2.6.6 to install argparse:

$ wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
$ sudo rpm -i epel-release-6-8.noarch.rpm
$ rm epel-release-6-8.noarch.rpm
$ sudo yum install python-argparse

In order to obtain more information about the script and its use, run it with the '-h' option:

$ sudo ~/make_sdimage.py -h
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=,format=,
                 size=[,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  [-P ...] -P 

The files required to create the SD card image can be acquired in 2 ways:

• Delivered as part of the precompiled binaries package, downloaded from Release Contents
• Rebuild the GHRD, Linux kernel, root filesystem, and u-boot, using Quartus and Yocto (or similar tool chain)

When building the files using the tool flows, use the table below to help locate the files after the build completes. It can be helpful to copy all the required files to an sdcard directory along with the make_sdimage.py script and run the script from that sdcard directory. The names used in the table below match those in the GHRD and the example usage of the script shown below the table. Note that the file names listed in the table are links to the build output target files. You will need to follow the links to their target destination file and copy that file to the sdcard directory. The target file names include one or more of the following suffixes: machine name, version number, date/timestamp. The make_sdimage.py script does not support the use of links when specifying the filenames.

Item	Source	File Location	Copy to sdcard directory as
Preloader image	Quartus GHRD Build	/sockit_ghrd/software/spl_bsp/preloader-mkpimage.bin*	preloader-mkpimage.bin
Compressed FPGA configuration file	^	/sockit_ghrd/output_files/soc_system.rbf	soc_system.rbf
Device Tree Blob file	^	/sockit_ghrd/soc_system.dtb	soc_system.dtb
U-boot script for configuring FPGA	^	/sockit-ghrd/u-boot.scr	u-boot.scr
U-boot image	Yocto Build	/angstrom-socfpga/deploy/glibc/images/cyclone5/u-boot-cyclone5.img**	u-boot-sockit.img
Compressed Linux kernel image file	^	/angstrom-socfpga/deploy/glibc/images/cyclone5/zImage	zImage
Linux root filesystem	^	/angstrom-socfpga/deploy/glibc/images/cyclone5/sockit-gsrd-console-image.tar.xz	extract to /rootfs (see below)

*Note: if using the make flow, this file will be located at /sockit_ghrd/software/preloader-mkpimage.bin
**Note: u-boot can also be build from the Quartus GHRD flow.

Creating SD Card Image Using Prebuilt Binaries

Re-create the SD card image by using the precompiled binaries package and performing the following commands. Ensure you have the linux-sockit-gsrd-15.1-bin.tar.gz file in the current folder (sdcard) or change paths accordingly.

1. Create rootfs folder for the root filesystem and extract the files from the archive:

$ tar xvzf linux-sockit-gsrd-15.1-bin.tar.gz
$ cd linux-sockit-gsrd-15.1-bin
$ mkdir rootfs
$ cd rootfs

Extract the files using sudo to ensure that root is the owner of the files in rootfs:

$ sudo tar xf ../sockit-gsrd-image.tar.xz
$ cd  .. 

2. Call the make_sdimage.py script:

$ sudo ./make_sdimage.py \
-f \
-P preloader-mkpimage.bin,u-boot-sockit.img,num=3,format=raw,size=10M,type=A2 \
-P rootfs/*,num=2,format=ext3,size=1200M \
-P zImage,u-boot.scr,soc_system.rbf,soc_system.dtb,num=1,format=vfat,size=300M \
-s 1700M  \
-n sockit-gsrd-sd-card.img

Creating SD Card Image Using Rebuilt Binaries

Assemble the rebuilt binaries according to the table above.

Call the make_sdimage.py script:

$ sudo ./make_sdimage.py \
-f \
-P preloader-mkpimage.bin,u-boot-sockit.img,num=3,format=raw,size=10M,type=A2 \
-P rootfs/*,num=2,format=ext3,size=1200M \
-P zImage,u-boot.scr,soc_system.rbf,soc_system.dtb,num=1,format=vfat,size=300M \
-s 1700M  \
-n sockit-gsrd-sd-card.img

Copying the image to the SD Card

Determine the device name by running the command below before and after plugging in the SD card reader into the host.

$ cat /proc/partitions

The device name can also be identified using a GUI utility on your Linux host such as gnome-disks.

Next, clone the image to the SD card

$ sudo dd if=sockit-gsrd_sd_card.img of=/dev/sdx bs=1M

Replace "sdx" with the device name of the SD card on your host system.
After the clone command finishes, flush the file system buffers:

$ sudo sync

TIP:
The cloning process can take several minutes and there is no feedback or progress indicator during the cloning process, leaving you to wonder if the system is hung. You can use the pv command to monitor the progress of the cloning process through a pipe.

$ sudo apt-get install pv
$ pv -tpreb sockit-gsrd_sd_card.img | sudo dd of=/dev/sdx bs=1M

replacing "sdx" with the device name of the SD card on your host system.

When the progress indicator shows 100%, wait for the command prompt to return and then flush the buffers:

$ sudo sync

Updating Individual Elements on the SD card

It is time consuming to write the whole SD image to the card each time a modification is made. Therefore it is often preferable to create the SD card and write it to the card once, then update different elements individually.

The following table presents how each item can be updated individually:

File	Update Procedure
zImage	Mount DOS SD card partition 1 and replace file with new one: $ sudo mkdir sdcard $ sudo mount /dev/sdx1 sdcard/ $ sudo cp <file_name> sdcard/ $ sudo umount sdcard
soc_system.rbf	^
soc_system.dtb	^
u-boot.scr	^
preloader-mkpimage.bin	$ sudo dd if=preloader-mkpimage.bin of=/dev/sdx3 bs=64k seek=0
u-boot-sockit.img	$ sudo dd if=u-boot-sockit.img of=/dev/sdx3 bs=64k seek=4
root filesystem	$ sudo dd if=sockit-gsrd-image.ext3 of=/dev/sdx2

Replace "sdx" in the command above with the device name of the SD card on your host system. You can find out the device name by running $ cat /proc/partitionsbefore and after plugging in the card reader into the host.

Notes:

It can be possible that the python script fails creating a loopback-device. To fix this open the script in an editor and substitute the term "-s" with "--show" at the row where losetup is called.