Introduction

This page presents the instructions on how to rebuild Linux by using the Yocto Source Package.

The Yocto Source package is an installer file provided by Altera that contains the Yocto build system, Yocto recipes and also the necessary dependencies to compile the Altera Linux bootloader, kernel and root filesystem.

Note: the Yocto build system and recipes for Altera Linux can be also obtained from the Git trees. See Linux - Getting Started Using Git Trees section for details on that. If the Git tree option is used, all the necessary dependencies would be downloaded from Internet.

For more details about Yocto see Altera Yocto Project User Manual (Danny).

Host Setup

The Altera Linux Yocto Source package was tested to build correctly with CentOS 6.3 and Ubuntu 12.04. It may also work with other distributions. For a list of distributions against which Yocto project was tested see https://wiki.yoctoproject.org/wiki/Distribution_Support. This section presents the packages that need to be installed on the host PC to allow the Yocto Source Package to be built. Since each machine may have been installed in a different way, the packages listed here are not an exhaustive list. Add packages as necessary if you encounter issues.

CentOS 6.3

These are the required packages that need to be installed:

$ sudo yum update
$ sudo yum groupinstall "Development Tools"
$ sudo yum install texi2html texinfo glibc-devel chrpath

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

$ sudo yum install glibc.i686 libgcc.i686 libstdc++.i686 glibc-devel.i686 ncurses-libs.i686 zlib.i686 

Ubuntu 12.04

These are the required packages that need to be installed:

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install 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

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

$ sudo apt-get install ia32-libs

Ubuntu 13.10 - Saucy Salamander

As per 12.04 above, except ia32-libs no longer exists in Saucy.

sudo apt-get install libqt4-gui:i386 itcl3:i386 itcl3-dev:i386 libgomp1:i386 libqtwebkit4:i386 libtbb2:i386 tcl8.5-lib:i386 tcl8.5-dev:i386

The above list was guessed from the output of ldd and apt-file

SoC EDS

The Altera SoC EDS toolset needs to be installed, since it provides the mkpimage tool that adds the BootROM signature on top of the Preloader image.

The SoC EDS can be obtained from https://www.altera.com/download/software/soc-eds. If you do not have a license, follow the instructions from the mentioned web page to obtain the free Web Edition license.

Obtaining Yocto Source Package

The Altera Yocto Source Package can be downloaded from the Altera website. The following commands can be used to dowload the package and mark it as executable:

$ wget http://download.altera.com/akdlm/software/acdsinst/13.0/156/ib_installers/linux-socfpga-13.02-RC10-src.bsx
$ chmod +x linux-socfpga-13.02-RC10-src.bsx

Setting Up Yocto

The Yocto Source Package may be installed in a publicly accessible location, as this step can be shared by all the users on the system (or on the filesystem if your company uses a network share). The default location is /opt/altera-linux. If you wish to use this location, you will likely need root access in order to access this directory. This is why the command shown below is ran using sudo.

$ sudo ./linux-socfpga-13.02-RC10-src.bsx

The next step is to install a local set of Yocto recipes. This could be done in a shared location, but if someone wants or needs to modify them they should have their own version. The default install location for this is within your home directory:

$ /opt/altera-linux/bin/install_altera_socfpga_src.sh ~/yocto

Last step is to create a build directory. By keeping this separate from your yocto source you can erase your entire build without fear of deleting your yocto sources. Also, you can have several build directories, each with its own configuration, all based on the same yocto source. The script serves 2 purposes. First, it creates the new build directory using Altera’s default configuration. Secondly, it sets some shell variables that are required for building.

$ source ~/yocto/altera-init ~/yocto/build

Note: If you start a new shell you will need to run the above command to set the shell variables again.

Building U-Boot/Kernel/Rootfs

In order to build u-boot from within the build directory you need to execute this command:

$ bitbake virtual/bootloader

or the equivalent:

$ bitbake u-boot

In order to build linux from within the build directory:

$ bitbake virtual/kernel

or the equivalent:

$ bitbake linux-altera

In order to build the root filesystem:

$ bitbake altera-image

If you wish to build a much smaller filesystem for small boot mediums:

$ bitbake altera-image-minimal

The first time you build the Yocto Source Package it may take up to several hours depending on your host machine.

Once finished, all images should be generated in ~/build/tmp/deploy/images. Some of the most important files created are:

File	Description
u-boot-spl-socfpga_cyclone5	SPL Preloader ELF file
u-boot-spl-socfpga_cyclone5.bin	SPL Preloader Binary
u-boot-socfpga_cyclone5	U-Boot ELF file
u-boot-socfpga_cyclone5.bin	U-Boot binary file
u-boot-socfpga_cyclone5.img	U-Boot image
socfpga_cyclone5.dtb	Device Tree Binary
vmlinux	Kernel ELF file
uImage	Kernel Image
altera-image-socfpga_cyclone5.cpio	Root filesystem in cpio archive format
altera-image-socfpga_cyclone5.ext3	Root filesystem as ext3 image
altera-image-socfpga_cyclone5.jffs2	Root filesystem as jffs2 image
altera-image-minimal-socfpga_cyclone5.jffs2	Minimal root filesystem as jffs2 image
altera-image-socfpga_cyclone5.tar.gz	Root filesystem in tar gzip archive format

The above files are actually links to the actual build resulted files. Each build file has a timestamp attached to its name and each time it it rebuilt, Yocto updates the link to point to the latest file.

Creating SD Card Image

To boot the linux images on SoC FPGA development kit, you need to write the images you just built with Yocto into one of the two Flash devices: SDMMC or QSPI. For this guide, we will use SDMMC due to its easy detachability. For SDMMC boot, all boot images will be located inside SD/MMC card. A script is provided with the release that will create an SD card image, ready to be deployed.

The script relies on a tool, named mkpimage, which creates the correct preloader image that the SoCFPGA Boot ROM accepts.This tool is provided with the SoC EDS release. See SoC EDS section for instructions.

After SoC EDS is installed, run the the following commands to locate mkpimagetool:

$ ~/altera/13.0/embedded/embedded_command_shell.sh
$ which mkpimage

The following files resulted from the Yocto build will be used, from ~/yocto/build/tmp/deploy/images:

File	Description
u-boot-spl-socfpga_cyclone5.bin	SPL Preloader Binary
u-boot-socfpga_cyclone5.img	U-Boot image
socfpga_cyclone5.dtb	Device Tree Binary
uImage	Kernel Image
altera-image-socfpga_cyclone5.tar.gz	Root File System

The following commands can be used to create the SD card image:

$ cd ~/yocto/build/tmp/deploy/images
$ cp -f socfpga_cyclone5.dtb socfpga.dtb
$ mkdir rootfs
$ cd rootfs
$ sudo tar xzf ../altera-image-socfpga_cyclone5.tar.gz
$ cd ..
$ sudo /opt/altera-linux/bin/make_sdimage.sh \
  -k uImage,socfpga.dtb\
  -rp u-boot-spl-socfpga_cyclone5.bin \
  -t /home/<user>/altera/13.0/embedded/host_tools/altera/mkpimage/mkpimage \
  -b u-boot-socfpga_cyclone5.img \
  -r rootfs/ \
  -o sd_image_yocto.bin

The above commands do the following:

• Make a copy of the socfpga_cyclone5.dtb as socfpga.dtb because that is the name that U-boot expects to see
• Extracts the root file system into a folder, using sudo to be able to create the device nodes
• Invokes the make_sdimage.sh script to create the SD card image named sd_image_yocto.bin. This is also executed using sudo because it uses system utilities.

Notes:

• The above commands assume default installation paths were used for all tools. Update accordingly if non-default paths were used.
• Please replace <user> with your user name.

You can also run make_sdimage.sh as follows, without parameters, to obtain more information about the tool:

$ /opt/altera-linux/bin/make_sdimage.sh

Using SD Card Image

See Linux Getting Started on Altera SoC Development Board - Using SD Card Image for instructions on how to use the SD card image to boot Linux. Simply use the newly created SD card image instead of the precompiled one.

Partially Updating SD Card

This section presents how to update various parts on the SD card, without having to re-create and write to the SD card the whole image. You will first need to have a working SD card before being able to run the commands presented in this section.

The commands presented assume the SD card device is /dev/sdx. Refer to Linux Getting Started on Altera SoC Development Board - Using SD Card Image for instructions on how to determine which device corresponds to the SD card reader on your host PC.

Updating SPL Preloader:

$ sudo dd if=u-boot-spl-socfpga_cyclone5.img of=/dev/sdx3 bs=64k seek=0

Updating U-boot Image

$ sudo dd if=u-boot-socfpga_cyclone5.img of=/dev/sdx3 bs=64K seek=4

Updating Device Tree Binary:

$ sudo mkdir sdcard
$ sudo mount /dev/sdx1 sdcard/
$ sudo cp socfpga_cyclone5.dtb sdcard/socfpga.dtb
$ sudo umount sdcard/

Updating Kernel Image:

$ sudo mkdir sdcard
$ sudo mount /dev/sdx1 sdcard/
$ sudo cp uImage-socfpga_cyclone5.bin sdcard/uImage
$ sudo umount sdcard/

Updating Root Filesystem:

$ sudo dd if=altera-image-socfpga_cyclone5.ext3 of=/dev/sdx2