initramfs Example Use Case

This article demonstrates how to boot an Intel PSG SoC system using initramfs, specifically to offer a simplified method to modify or update non-removable boot media such as eMMC flash. On systems that utilize removable boot media like micro SD cards, testing new kernels, device trees, or root filesystems during the development stage can be easily done by removing the card and inserting into a host PC to update the files of interest. But what about boards that use eMMC flash as boot media? Updating this boot source can be more time consuming since it must be modified on the live board from another OS not running from the eMMC. If there is an Ethernet interface available, this can be done by booting over network using TFTP and NFS. This process uses bootloader software such and U-Boot and a Linux host setup to act as the TFTP and NFS server. The Linux kernel, device tree, and potentially the FPGA configuration file are all loaded from the server using TFTP. Loading the root filesystem over network is done with NFS. The NFS setup is often the source of most problems when setting up the network server, compared to TFTP. There are a number of kernel command line parameters passed during the boot process and when problems arise, it is often at the stage of loading the root filesystem from NFS. If a minimal root file system could be loaded with the kernel using TFTP - one that provides common utilities like fdisk to modify the eMMC - then this network boot process can be simplified by using only TFTP. Fortunately, this can be accomplish using initramfs. An initramfs is a completely self contained Linux kernel + cpio format achived root filesystem. During kernel loading, the cpio archive is extracted and the init program is executed, completing the boot process. For more details, refer to the documentation in the Linux source tree under /Documentation/filesystems/ramfs-rootfs-initramfs.txt.

Note that this process assumes that the user has a board with the eMMC flash already partitioned and programmed with some image, typically the board manufacturer's default factory image, and the goal is to update the eMMC with the user's image. The initial process of partitioning and writing to the eMMC is usually done through a tool such as ARM DS-5 and is not covered in this article.

REFLEX CES offers a number of Intel PSG based SoC boards, using both Arria 10 and Stratix 10 families. Some of these boards use only non-removable eMMC boot flash for the processor subsystem. An example will be presented to build an initramfs which will include the Linux kernel and a minimal root filesystem that can be used specifically for updating the target board's eMMC flash. This could also be used for initial board bring-up by booting over network using only TFTP. This example supports two boards by REFLEX CES:

• Achilles SOM - Arria 10 System on Module with FMC connectors
• COMXpress SOM - Stratix 10 System on Module, COM Express Basic form factor with Type 7 pinout

The Yocto Project build flow is used to generate a minimal Poky reference distribution filesystem and Linux kernel. The steps for building the initramfs are given below if you would like to build from scratch and add your own customization. Precompiled images are also provided for both of these boards so you can skip the build step if you just want to make use of the provided initramfs image.

Prerequisites and Related Articles

Prerequisites:

• You must have a TFTP server setup and running. If you need to set one up, refer the article below (Booting Altera SoC FPGA from Network using TFTP and NFS).
• This example uses some variable values as defined in the referenced article, including:
  • Network with gateway IP address at 192.168.1.1 and DHCP clients connecting from 192.168.1.100 to 192.168.1.249.
  • TFTP/NFS server IP address at 192.168.1.155.
  • Modify the IP addresses in the instructions below where appropriate to match your network settings.
• This example assumes you are using the SOM in its factory default condition. This means certain U-Boot environment variables may not be present if you updated to a newer version of U-Boot. Follow the additional instructions below to add them if necessary.

The Linux distribution used was Kubuntu 18.04.2 LTS. Other distributions may work but have not been tested.

Other useful Rocketboards articles:

• Building initramfs kernels
• Yocto: Building Yocto with meta-altera
• Booting Altera SoC FPGA from Network using TFTP and NFS

Building initramfs with Yocto

If you want to skip building your own and just use the precompiled binaries, scroll down to Table 1 below.

1. Create a working directory for the build and move to that directory:

For Achilles:

$ mkdir -p ~/work/initramfs/achilles && cd ~/work/initramfs/achilles

For COMXpress:

$ mkdir -p ~/work/initramfs/comxpress && cd ~/work/initramfs/comxpress

2. Check that your system has all the required build dependencies for Yocto:

$ wget https://raw.githubusercontent.com/dnegvesky/build-scripts/thud/yocto-packages.sh
$ chmod +x yocto-packages.sh
$ sudo ./yocto-packages.sh

3. Clone the required repositories:

$ git clone -b warrior git://git.yoctoproject.org/poky.git
$ git clone -b master git://github.com/kraj/meta-altera.git

4. Modify the MACHINE .conf file from the meta-altera layer for our build:

For Achilles (Arria 10):

$ sed --follow-symlinks -i '/IMAGE_FSTYPES/d' meta-altera/conf/machine/arria10.conf
$ sed --follow-symlinks -i '$a \IMAGE_FSTYPES += "cpio.gz"' meta-altera/conf/machine/arria10.conf
$ sed --follow-symlinks -i '$a \INITRAMFS_IMAGE = "core-image-minimal"' meta-altera/conf/machine/arria10.conf

For COMXpress (Stratix 10):

$ sed --follow-symlinks -i '/IMAGE_FSTYPES/d' meta-altera/conf/machine/stratix10.conf
$ sed --follow-symlinks -i '$a \IMAGE_FSTYPES += "cpio.gz"' meta-altera/conf/machine/stratix10.conf
$ sed --follow-symlinks -i '$a \INITRAMFS_IMAGE = "core-image-minimal"' meta-altera/conf/machine/stratix10.conf

5. Run the Open Embedded configuration script:

$ source poky/oe-init-build-env ./build

6. Modify the bblayers.conf file to add the meta-altera layer:

$ sed --follow-symlinks -i "/meta-yocto-bsp/a \  \${TOPDIR}/../meta-altera \\\\" conf/bblayers.conf

7. Modify local.conf to specify the MACHINE type and add build settings:

For Achilles:

$ sed --follow-symlinks -i '$a \\MACHINE = "arria10"' conf/local.conf

For COMXpress:

$ sed --follow-symlinks -i '$a \\MACHINE = "stratix10"' conf/local.conf

Specify the kernel version:

$ sed --follow-symlinks -i '$a \PREFERRED_PROVIDER_virtual/kernel = "linux-altera-ltsi"' conf/local.conf
$ sed --follow-symlinks -i '$a \PREFERRED_VERSION_linux-altera-ltsi = "4.14.73%"' conf/local.conf

Bundle the initramfs image with the kernel:

$ sed --follow-symlinks -i '$a \INITRAMFS_IMAGE_BUNDLE = "1"' conf/local.conf

8. Include Dropbear so we can ssh/scp to/from the target:

$ sed -i '$a \EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"' conf/local.conf

9. Launch the build:

$ bitbake core-image-minimal

When the build completes, the kernel image with cpio archive will be located in the build path as shown in Table 1 below. As usual with Yocto, this is a symbolic link to the actual .bin file in the same directory which will have a much longer name that includes some kernel info, git revision info, machine name, and date/time stamp. Be sure to copy the file that starts with "Image-initramfs..." and not just "Image..." because an unbundled kernel-only image is also created in this directory. Copy this file over to your TFTP directory that you have setup previously.

At this point, the instructions are the same for building the initramfs from scratch or using the precompiled binaries, and apply equally to either the Achilles or COMXpress boards. The Image file should now be copied to the appropriate location on your TFTP server. In this example, we are using /srv/tftp/initramfs. We will also need the device tree blob for the board, and we will use the default .dtb file in the board support package provided with the REFLEX CES board. After extracting the board package .zip file, the .dtb can be found in the location shown in Table 1 below:

Table 1

Board	File(s) to copy	Source of File	Precompiled Binary Archive	md5sum
Achilles	/build/tmp/deploy/images/stratix10/zImage-initramfs-arria10.bin*	Yocto build output	achilles-initramfs.tar.gz	c66596246ba56c953cb1f876bd175060
^	/HPS/kernel/bin/linuxDT.dtb	BSP archive**	^	^
COMXpress	/build/tmp/deploy/images/stratix10/Image-initramfs-stratix10.bin*	Yocto build output	comxpress-initramfs.tar.gz	15bf2afc7edfe4c1fdaaf87ce70661dd
^	/HPS/kernel/bin/socfpga_stratix10_comxpress.dtb	BSP archive**	^	^
^	/HPS/UBoot/bin/u-boot.scr	^	^	^

* Remember to copy the full filename pointed to by this sym link
** BSP archive is provided by REFLEX CES after board purchase

Notice that the COMXpress board requires an additional script file to configure the HPS/FPGA firewall and bridges on Stratix 10.

Copy these other file(s) over to the same directory on the TFTP server as the initramfs image. Be sure to restart the TFTP server after copying the files:

$ sudo service tftpd-hpa restart

Modifying U-Boot Environment Variables and Booting initramfs

Next we need to modify the default U-Boot environment by adding some variables to support booting with the new initramfs.

Setup the REFLEX CES Achilles or COMXpress board and connect the USB cable from a host PC to the board to allow for the connection through a terminal program such as PuTTY. Power on the board and connect to it with your terminal program. Interrupt the boot process in U-Boot before the timeout expires. At the U-Boot prompt, add the following environment variables:

SOCFPGA_STRATIX10 # setenv initramfs-dir initramfs

Note that our TFTP server directory was set in /etc/default/tftpd-hpa using the variable TFTP_DIRECTORY="/srv/tftp/", so by setting our initramfs-dir variable to initramfs, the full path becomes /srv/tftp/initramfs when passed to the server from U-Boot. If your TFTP server uses a different path, modify the variable accordingly.

In this next setting, we are using several of the REFLEX CES factory default u-boot variables. If you have previously modified these u-boot variables, you will have to make the appropriate changes below.

If using the Achilles SOM:

RxC_SoMA10_Turbo # setenv initramfs-boot 'setenv bootargs earlycon debug ignore_loglevel console=ttyS0,115200 root=/dev/ram rw; tftp ${loadaddr} ${initramfs-dir}/${bootimage}; tftp ${fdtaddr} ${initramfs-dir}/${fdtimage}; bootz ${loadaddr} - ${fdtaddr}'

If you have updated U-Boot on Achilles, for example by following the tutorial found at Achilles SOM - Arria 10 System on Module with FMC connectors, you will need to add these additional environment variables:

ACHILLES_A10SOM # setenv ipaddr 192.168.1.222    (Set this to any unused IP address on your network)
ACHILLES_A10SOM # setenv serverip 192.168.1.155  (Set this to your TFTP/NFS server IP address)
ACHILLES_A10SOM # setenv bootimage zImage
ACHILLES_A10SOM # setenv fdtimage linuxDT.dtb
ACHILLES_A10SOM # setenv fdtaddr 0x100

If using the COMXpress Module:

SOCFPGA_STRATIX10 # setenv initramfs-boot 'setenv bootargs earlycon debug ignore_loglevel console=ttyS0,115200 root=/dev/ram rw; tftp ${loadaddr} ${initramfs-dir}/${kImage}; tftp ${fdt_addr} ${initramfs-dir}/${fdtimage}; tftp ${scriptaddr} ${initramfs-dir}/${scriptfile}; source ${scriptaddr}; booti ${loadaddr} - ${fdt_addr}'

The remaining commands apply to either COMXpress or Achilles (COMXpress prompt is shown in examples).

Save the new environment variables so they are persistent on the next boot:

SOCFPGA_STRATIX10 # saveenv

Ping your TFTP server just to make sure the connection is active:

SOCFPGA_STRATIX10 # ping 192.168.1.155 (replace this with your TFTP server's IP address)

If your connection is alive, you are ready to boot the initramfs:

SOCFPGA_STRATIX10 # run initramfs-boot

Once you reach the login prompt, enter the default password: root

Poky (Yocto Project Reference Distro) 2.7.1 stratix10 /dev/ttyS0

stratix10 login: root

Now we are ready to copy files over to the target board and update the eMMC partitions using scp. In this example, we are copying a new kernel image and root filesystem archive from a Yocto build for the COMXpress module. The steps are similar for the Achilles module. We will not be updating the u-boot image at this time. Take care when updating the u-boot image. If this is corrupted or otherwise non-functional, you will have to use a tool such as DS-5 to restore the factory default u-boot image before you can perform another network boot. For reference, below is the eMMC partition map found in the COMXpress Reference Manual.

First find the IP address of the board. We will use this in the scp command in a few steps.

root@stratix10:~# ifconfig
eth0      Link encap:Ethernet  HWaddr 12:82:E0:85:4B:8B
          inet addr:192.168.1.159  Bcast:192.168.1.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:213 errors:0 dropped:0 overruns:0 frame:0
          TX packets:4 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:14921 (14.5 KiB)  TX bytes:1068 (1.0 KiB)
          Interrupt:9 Base address:0x2000

Next, mount the eMMC partition(s) that you want to update. We will use the /media directory for this.

root@stratix10:# mkdir -p /media/emmcp1
root@stratix10:# mkdir -p /media/emmcp2
root@stratix10:# mount /dev/mmcblk0p1 /media/emmcp1
root@stratix10:# mount /dev/mmcblk0p2 /media/emmcp2

Before we copy new files over, you might choose to rename the exiting files in case you need to revert back to these factory default files. We will delete the existing rootfs to use the new one. If there are issues with the new rootfs, the factory restore archive (also available in the board BSP) can be copied back and extracted using this same process.

root@stratix10:# cd /media/emmcp1
root@stratix10:# mv Image Image-factory-restore
root@stratix10:# mv socfpga_stratix10_comxpress.dtb socfpga_stratix10_comxpress-factory-restore.dtb
root@stratix10:# cd /media/emmcp2
root@stratix10:# rm -R *

Now back on the host PC that contains the files you want to copy, open a terminal and browse to the directory containing those files:

$ cd ~/work/comxpress/angstrom-v2018.06-yocto2.5/deploy/glibc/images/comxpress
$ scp Image--4.14.73-ltsi+git0+3286950e98-r0.2-socfpga_stratix10_comxpress-20190507144249.dtb root@192.168.1.159:/media/emmcp1/socfpga_stratix10_comxpress.dtb
$ scp Image--4.14.73-ltsi+git0+3286950e98-r0.2-comxpress-20190507144249.bin root@192.168.1.159:/media/emmcp1/Image
$ scp Angstrom-comxpress-xfce-image-glibc-ipk-v2018.06-comxpress.rootfs.tar.xz root@192.168.1.159:/media/emmcp2/rootfs.tar.xz

Now back on the target board, extract the new root filesystem archive:

root@stratix10:# tar xf rootfs.tar.xz
root@stratix10:# rm rootfs.tar.xz

Next we can reboot the board and test the new kernel and rootfs:

root@stratix10:# reboot

If your builds were successful, the board should now boot using your new build elements.