Introduction

This guide will demonstrate the steps to create the SD Image for the 17.1 GHRD with Linux Kernel socfpga-4.9.78-ltsi and Angstrom 2017.06. There are some changes associated to the new LTSI kernel therefore there would also be steps to create the Linux components of the sdimage individually.

The released Linux Tags in https://github.com/altera-opensource are as follow:

Repo	Branch	Commit ID	Release Tag
linux-socfpga	socfpga-4.9.78-ltsi	bdf910b1939e45beef022239bda381a2b11a6337	ACDS17.1_REL_GSRD_UPDATE1_PR
uboot-socfpga	socfpga_v2013.01.01	239ae4dbaab424881fe9f4a11dc354abdd53cb1e	ACDS17.1_REL_GSRD_UPDATE1_PR
linux-redesigns	master	02663381bc0acbc940cb454db7a648a07bc4a75c	ACDS17.1_REL_GSRD_UPDATE1_PR
meta-altera	angstrom-v2016.12-yocto2.2	22e6c92ca45741efe2763ceb06e0e98a529bf96b	ACDS17.1_REL_GSRD_UPDATE1_PR
meta-altera-refdes	master	1e64619f42589d43207d5c4926ba4268d90459c2	ACDS17.1_REL_GSRD_UPDATE1_PR

The rbf creation for GHRD remains the same as 17.1

A10	https://rocketboards.org/foswiki/Documentation/A10GSRDCompilingHardwareDesign171
AV	https://rocketboards.org/foswiki/Documentation/AVGSRDCompileHardwareDesign
CV	https://rocketboards.org/foswiki/Documentation/GSRDCompileHardwareDesign

This guide would focus on:

1. Creation of the Device Tree based on 17.1 top level dts and how to change it manually to run with new kernel
2. Create Angstrom Root File System with Kernel Image
3. Build Kernel from github
4. Build CV/AV Bootloader from github
5. Create SD Image for A10, AV and CV

A10 SD Image contents

File	Description
zImage	Kernel Image
ghrd_10as066n2.core.rbf	GHRD Raw Binary Core File
ghrd_10as066n2.periph.rbf	GHRD Raw Binary Peripheral File
socfpga_arria10_socdk_sdmmc.dtb	Device tree blob for Arria10
uboot_w_dtb-mkpimage.bin	Uboot binary image
Angstrom Rootfs	Root file system

AV SD Image contents

File	Description
zImage	Kernel Image
ghrd_5astfd5k3.rbf	GHRD Raw Binary File
socfpga.dtb	Device tree blob for Arria10
uboot_w_dtb-mkpimage.bin	Uboot binary image
Angstrom Rootfs	Root file system

CV SD Image contents

File	Description
zImage	Kernel Image
soc_system.rbf	GHRD Raw Binary File
socfpga.dtb	Device tree blob for Arria10
preloader-mkpimage.bin	Uboot pre-loader binary
Angstrom Rootfs	Root file system

Create Device Tree

To craft the device tree please refer to the link below: https://rocketboards.org/foswiki/Documentation/HOWTOCreateADeviceTree

The top level device tree structure file can be obtained from

AV	https://releases.rocketboards.org-interim/av_socfpga.dts
CV	https://releases.rocketboards.org-interim/cv_socfpga.dts
A10	https://releases.rocketboards.org-interim/a10_socfpga.dts

The device tree blob created from the instructions above would be later used in the creation of the SD image. The default naming convention that the uboot recognizes would be :

A10	"socfpga_arria10_socdk_sdmmc.dtb"
AV	"socfpga.dtb"
CV	"socfpga.dtb"

Next section the instructions on how to build the following Linux items:

• U-Boot
• Linux Kernel
• Linux Root Filesystem

GSRD tagging information

For all the tags that is released with GSRD, please refer to the page GSRD tagging information

Host Setup for Angstrom

Angstrom distribution was tested see https://wiki.yoctoproject.org/wiki/Distribution_Support.

These are the required packages that need to be installed:

• phablet-tools
• sed
• wget
• cvs
• subversion
• git-core
• coreutils
• unzip
• texi2html
• texinfo
• libsdl1.2-dev
• docbook-utils
• gawk
• python-pysqlite2
• diffstat
• help2man
• make
• gcc
• build-essential
• g++
• desktop-file-utils
• chrpath
• libgl1-mesa-dev
• libglu1-mesa-dev
• mercurial
• autoconf
• automake
• groff
• libtool
• xterm
• lib32z1

If the host machine runs the 64bit version of the OS, then the following additional packages need to be installed:

• ia32-libs
• lib32stdc++6

Rootfs Using Angstrom distribution

Note** Only 2017.06 of Angstrom have been fully tested for Golden System Reference Design (GSRD) User Manuals. The current version of Angstrom 2017.12 tests is still ongoing

The commands for cloning the Yocto Project git trees and building Yocto Project are:

$ cd ~
$ mkdir angstrom-build
$ cd angstrom-build
$ wget https://releases.rocketboards.org/s10-eap-release/altera.xml 
$ wget http://commondatastorage.googleapis.com/git-repo-downloads/repo
$ chmod 777 repo
$ export PATH=$PATH:~/angstrom-build
$ repo init -u git://github.com/Angstrom-distribution/angstrom-manifest -b angstrom-v2017.06-yocto2.3
$ mkdir -p .repo/local_manifests
$ mv altera.xml .repo/local_manifests/ #replacing kraj/meta-altera for interim solution commits
$ repo sync
$ MACHINE=stratix10 . ./setup-environment
$ sed -i '/meta-altera/a \ \ ${TOPDIR}\/layers\/meta-altera-refdes \\' conf/bblayers.conf # This is to add the meta-altera-refdes layer to conf/bblayers.conf
$ sed -i '/meta-atmel/d' conf/bblayers.conf # removing packages that are not needed
$ sed -i '/meta-optee/d' conf/bblayers.conf # This has conflicting packages 
$ export KERNEL_PROVIDER=linux-altera-ltsi
$ export KERNEL_TAG=refs/tags/ACDS17.1_REL_GSRD_UPDATE1_PR  # This is the released interim tag
$ export UBOOT_TAG=refs/tags/ACDS17.1_REL_GSRD_UPDATE1_PR  # This is the released interim tag
$ export KBRANCH=socfpga-4.9.78-ltsi
$ BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE KBRANCH KERNEL_TAG UBOOT_TAG KERNEL_PROVIDER"
$ bitbake gsrd-console-image 

Targetting Arria V / Cyclone V

In order to build the target against Arria V or Cyclone V, just replace arria10 with arria5 or cyclone5 in the above commands.

Building Kernel and U-Boot Separately From Git Trees

U-boot and Linux kernel can also be built directly from the git trees at https://github.com/altera-opensource/ This section presents instructions for cloning the git trees and building U-boot, Linux kernel and Yocto.

Component	Git address	Tag
Linux	linux-socfpga.git	ACDS17.1_REL_GSRD_UPDATE1_PR
U-Boot (CV/AV)	u-boot-socfpga.git	ACDS17.1_REL_GSRD_UPDATE1_PR

Build Toolchain

In case the U-boot or Linux kernel git trees are directly used, the build toolchain has to be manually downloaded. This section contains the instructions on how to download and setup the toolchain for this case.

Note that the build toolchain is provided with the Poky Yocto recipes. So when the Yocto Project git tree is used, the recipes will download the build chain automatically.

The steps necessary to download and setup the build toolchain are:

$ cd ~
$ wget https://releases.linaro.org/archive/14.04/components/toolchain/binaries/gcc-linaro-arm-linux-gnueabihf-4.8-2014.04_linux.tar.bz2
$ tar xjf gcc-linaro-arm-linux-gnueabihf-4.8-2014.04_linux.tar.bz2
$ export CROSS_COMPILE=~/gcc-linaro-arm-linux-gnueabihf-4.8-2014.04_linux/bin/arm-linux-gnueabihf-

Building U-Boot

This section presents instructions on how to clone the U-boot git tree and compile U-boot. It assumes that you have manually downloaded the build toolchain.

$ cd ~
$ git clone http://github.com/altera-opensource/u-boot-socfpga
$ cd u-boot-socfpga
$ git checkout -b Release Tag # Please refer build tag from reference page
$ export CROSS_COMPILE=~/gcc-linaro-arm-linux-gnueabihf-4.8-2014.04_linux/bin/arm-linux-gnueabihf-
$ make mrproper
$ make socfpga_cyclone5_config # Replace with socfpga_arria10_config or socfpga_arria5_config if you are building for different target platform
$ make

Notes:

• replace Release Tag with the name of the branch you want to use locally.
• replace make socfpga_cyclone5_config with make socfpga_arria5_config to compile the Arria V version, and make socfpga_arria10_config to compile Arria 10 bootloader

Some of the files that are created:

File	Description
u-boot	U-boot ELF file
u-boot.bin	U-boot binary file
u-boot.img	U-boot image file

Building Linux Kernel

This section presents instructions on how to clone the Linux kernel git tree and compile the Linux kernel. It assumes that you have manually downloaded the build toolchain.

$ cd ~
$ git clone https://github.com/altera-opensource/linux-socfpga
$ cd linux-socfpga
$ git checkout -b Release Tag # Refer to the tag in the above 
$ export CROSS_COMPILE=~/gcc-linaro-arm-linux-gnueabihf-4.8-2014.04_linux/bin/arm-linux-gnueabihf-
$ export ARCH=arm 
$ make socfpga_defconfig
$ make zImage

You can also compile the dtb for the kernel by following the above instruction and change the make target (last line) to the DTB target, for example, for Arria 10

$ make socfpga_arria10_socdk_sdmmc.dtb

You can find all the supported dts from {linux-socfpga}/arch/arm/boot/dts/

Note: replace Release Tag with the name of the branch you want to use locally.

Some of the files that are created:

File	Description
vmlinux	Linux Kernel ELF file
arch/arm/boot/zImage	Linux Kernel image

Creating SD Card Image Using Provided Script

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

This release of the GSRD includes a tool that can be used to create a bootable SD card image from the items mentioned in the table above. The tool is named make_sdimage.py and is available at https://releases.rocketboards.org/2017.10/gsrd/tools/make_sdimage.py.

Note that the script requires 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.6 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 tool, please 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

Creating SD Card Image

This section presents how to use the script to create the bootable GSRD Arria 10 SD Card.

Note that the image is already part of the GSRD binaries package. This procedure is required whenever a new SD card image needs to be created.

1. cd to a new folder and gather the required files into the current folder:

Item	Description
uboot_w_dtb-mkpimage.bin	U-Boot and U-Boot Device Tree Image
ghrd_10as066n2.core.rbf	Compressed FPGA configuration file
ghrd_10as066n2.periph.rbf	Compressed FPGA IO configuration file
socfpga_arria10_socdk_sdmmc.dtb	Linux Device Tree Blob
zImage	Compressed Linux kernel image
gsrd-console-image-arria10.tar.xz	Root filesystem as compressed tarball (built together with kernel image)

2. Get the SD image creation script from Release Tags into the current folder and make it executable:

$ chmod +x make_sdimage.py

3. Create the root filesystem to be put on the SD card image (GNU tar 1.27.1):

$ mkdir rootfs
$ cd  rootfs
$ sudo tar xf ../gsrd-console-image-arria10.tar.xz
$ cd ..

4. Call the make_sdimage.py script:

$ sudo make_sdimage.py  \
  -f \
  -P uboot_w_dtb-mkpimage.bin,num=3,format=raw,size=10M,type=A2  \
  -P rootfs/*,num=2,format=ext3,size=1500M  \
  -P zImage,ghrd_10as066n2.core.rbf,ghrd_10as066n2.periph.rbf,socfpga_arria10_socdk_sdmmc.dtb,num=1,format=vfat,size=500M  \
  -s 2G  \
  -n sdimage.img

This will create the file sd_card_image_a10.img.

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 /dev/sdx1 (FAT) on the host machine and update files accordingly: $ sudo mkdir sdcard $ sudo mount /dev/sdx1 sdcard/ $ sudo cp sdcard/ $ sudo umount sdcard
ghrd_10as066n2.core.rbf	^
ghrd_10as066n2.periph.rbf	^
socfpga_arria10_socdk_sdmmc.dtb	^
uboot_w_dtb-mkpimage.bin	$ sudo dd if=uboot_w_dtb-mkpimage.bin of=/dev/sdx3 bs=64k seek=0
root filesystem	Mount /dev/sdx2 (ext3 FS) on the host machine and updatefiles accordingly

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

Updating Individual Elements on the SD card for Arria5 or Cyclone5

$ cd ~/linux-socfpga-gsrd-av-bin
$ mkdir rootfs
$ xz -d gsrd-console-image-arria5.tar.xz 
$ sudo tar xf gsrd-console-image-arria5.tar -C rootfs

Call the make_sdimage.py script:

$ cd ~/linux-socfpga-gsrd-av-bin
$ sudo ~/make_sdimage.py  \
  -f \
  -P preloader-mkpimage.bin,u-boot-arria5.img,num=3,format=raw,size=10M,type=A2  \
  -P rootfs/*,num=2,format=ext3,size=1500M  \
  -P zImage,u-boot.scr,soc_system.rbf,socfpga.dtb,num=1,format=vfat,size=500M  \
  -s 2G  \
  -n sd_card_image_arria5.bin

This will create the file sd_card_image_arria5.bin.

Creating SD Card Image Using Rebuilt Binaries in Arria5 or Cyclone5

This section presents how to build the SD card image for Arria V from the rebuilt binaries.

This is very similar with creating using Prebuilt binaries, except using the files from where they are built. The default locations are used:

Default File Location	Comment
~/angstrom/build/tmp/deploy/images/zImage	Built by Yocto or Github
u-boot-arria5.img	^
~/angstrom/build/tmp/deploy/images/gsrd-console-image-arria5.tar.xz	^
~/av_soc_devkit_ghrd/output_files/ghrd_5astfd5k3.rbf	Part of GHRD
~/av_soc_devkit_ghrd/software/spl_bsp/preloader-mkpimage.bin	^
~/av_soc_devkit_ghrd/socfpga.dtb	^

Updating Individual Elements on the SD card

This section presents how to build the SD card image for Cyclone V from the rebuilt binaries.

This is very similar with creating using Prebuilt binaries, except using the files from where they are built. The default locations are used:

Default File Location	Comment
~/angstrom/build/tmp/deploy/images/zImage	Built by Yocto or from Github
u-boot-cyclone5.img	^
~/angstrom/build/tmp/deploy/images/gsrd-console-image-cyclone5.tar.xz	^
~/cv_soc_devkit_ghrd/output_files/soc_system.rbf	Part of GHRD
~/cv_soc_devkit_ghrd/software/spl_bsp/preloader-mkpimage.bin	^
~/cv_soc_devkit_ghrd/socfpga.dtb	^

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 /dev/sdx1 (FAT) on the host machine and update files accordingly: $ sudo mkdir sdcard $ sudo mount /dev/sdx1 sdcard/ $ sudo cp sdcard/ $ sudo umount sdcard
ghrd_5astfd5k3.rbf (AV) or soc_system.rbf (CV)	^
socfpga.dtb	^
u-boot.scr	^
preloader-mkpimage.bin	$ sudo dd if=preloader-mkpimage.bin of=/dev/sdx3 bs=64k seek=0
u-boot-arria5.img or u-boot-cyclone5.img	$ sudo dd if=u-boot-arria5.img of=/dev/sdx3 bs=64k seek=4
root filesystem	Mount /dev/sdx2 (ext3 FS) on the host machine and updatefiles accordingly

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

Errata of Known Issues

Powering up the SD Image for the first time could result in certain ttyS0 timeout. This is suspected to be related to the udev/hwdb configuration. Investigation to fix this is still ongoing