Introduction

This is the Altera Yocto User's Manual for Yocto. Here below, it is assumed that Yocto 'Danny' (8.0) is used.

What is Yocto?

Yocto is a community project, aiming at building Linux distributions for different architectures. The Yocto project relies on Open Embedded, a suite of tools, including bitbake, that take care of building source code.

Although Open Embedded (OE) is a project on its own, the source code of OE is provided with the Yocto project (consistency).

Yocto is becoming the defacto standard to build Linux source code, including the boot loader, the Linux kernel and the root file system images required to run a Linux operating system (OS) on an architecture.

The version of Yocto that Altera is currently shipping with its SOCFPGA Linux BSP releases is 8.0, aka Danny. Future releases of the SOCFPGA Linux BSP will provide the latest reasonable Yocto version available at release time.

Altera selected Yocto to build its SOCFPGA Linux BSP.

Open Embedded relies on a utility called 'bitbake' to build source code. Each package, like busybox, i2c-tools, etc, have an associated 'recipe' that describes the build process (where to get the source code, how to build, how to deploy to the root file system image). Yocto comes with a large set of recipes, located under the folder named 'meta'. Altera has added its own set of recipes, that are specific to SOCFPGA. These recipes are located under the folder named 'meta-socfpga'.

What are the requirements to run Yocto?

The Yocto project has been tested against a few distributions, as shown here. See the release notes and the SOCFPGA Linux BSP User's Manual to find out what Linux distribution the current SOCFPGA Linux BSP release has been tested against.

In order to run properly, a few packages need to be installed on the host distribution. Since the name of the packages as well the package installation procedure depend on the selected host distribution, please refer to the SOCFPGA Linux BSP User's Manual to find out more.

How is Altera's SOCFPGA Linux BSP organized?

The SOCFPGA Linux BSP releases are composed of two packages:

• The source code package, including the SOCFPGA Linux kernel source code, the SOCFPGA U-BOOT source code as well as the source code required to rebuild the root file system.
  The tool chain (GCC) is also included in source code form. Finally, the Yocto project is also included.
  An installation script is also provided
• The binary package, including pre-built images of the SOCFPGA kernel and boot loader, as well as a variety of file system images, ready to be used.

Obtaining Yocto Source Package

The Altera Yocto Source Package can be downloaded from https://releases.rocketboards.org/2013.11/gsrd/src/linux-socfpga-gsrd-13.1-src.bsx.

How to setup the Yocto environment?

First step is to make sure the source package can be executed. Run the following command to achieve this:

$ chmod +x linux-socfpga-gsrd-13.1-src.bsx

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-gsrd-13.1-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.

How does Yocto find the source code to build?

Yocto, by default, is configured to download the source code it needs automatically, on demand. However, depending on the network topology and security, these automatic download can prove difficult and prevent a user from building the SOCFPGA Linux BSP.

In order to minimize the problems, Altera provides the source code required to build the root file system configuration shipped with the SOCFPGA Linux BSP releases. Yocto is configured to check a local mirror first (the default location is /opt/linux-altera/sources) and then try download from the internet.

Yocto may download source code with a variety of network protocols. The protocol to be used is specified in the package's recipe. Examples of protocols are http, git, cvs, svn.

Should your network have a proxy, please make sure that the protocols required for the packages you need are enabled.

How to build the SOCFPGA Linux kernel as released

$ bitbake virtual/kernel

How to run an incremental build of the SOCFPGA Linux kernel after a change to the source code

Yocto will unpack linux from an archive included with the sdk. You can find these files within the build/tmp/work/socfpga_cyclone5-poky-linux-gnueabi/linux-altera-dist-1.0-r1/linux-socfpga. After modifying them you must force yocto to rebuild linux the Linux source, then tell it to rebuild the zImage file.

$ bitbake -f -c compile virtual/kernel; bitbake virtual/kernel

Although this will rebuild the zImage, it can take a while because it will not reuse any outputs from the prior build, and in some cases may rebuild the root filesystem. If you are in the role of modifying and rebuilding the kernel frequently, you may want to perform builds from within a devshell. Note that this should be done after having at least compiled the Linux kernel once in order to insure that all the prerequisite steps have been peformed for you (such as having built the gcc cross compiler)

$ bitbake -c devshell virtual/kernel

In the new shell, you must unset some of the variables that have been created for compiling apps

$ unset CFLAGS CPPFLAGS CXXFLAGS LDFLAGS MACHINE
$  $MAKE zImage CC="$CC" LD="$LD"

At this point new zImages will be available at arch/arm/boot/zImage

How to import the SOCFPGA Linux kernel source from a local directory

If you have the Linux source code locally, you can tell yocto to use it as the source code instead of the code in the included archive. To do this you will need to edit the local.conf file within your builds conf subdirectory and add the following lines to the end. Be sure to replace my-linux-source with the name of the directory your source resides in, and /home/username/my-linux-source with the full path name. Do not add a "/" to the end of the directory name.

PREFERRED_VERSION_linux-altera = "local"
LINUX_SRC_DIR = "/home/username/my-linux-source"

Yocto does not create a link to the original code, but instead copies the code. If you make changes to your source you can force yocto to update its copy by using the following command. Alternatively, you can edit your linux code within tmp/work/socfpga-5xs1-poky-linux-gnueabi/linux-altera-local-r1/my-linux-source directory.

$ bitbake -f -c fetch virtual/kernel

How to import the SOCFPGA u-boot boot loader source from a local directory

Like the Linux kernel, uboot can also be built from local sources by modifying the conf/local.conf file. Be sure to replace my-linux-source with the name of the directory your source resides in, and /home/username/my-linux-source with the full path name.

PREFERRED_VERSION_u-boot = "local"
U_BOOT_SRC_DIR = "/home/username/my-uboot-source"

To update the u-boot source to use your most recent version, use:

$ bitbake -f -c fetch virtual/bootloader

How to edit the kernel configuration?

$ bitbake -c menuconfig virtual/kernel

How to build the SOCFPFA u-boot boot loader as released

$ bitbake virtual/bootloader

How to build the SOCFPGA root file system as released

   $ bitbake altera-gsrd-image

Packages provided by Yocto

The rootfs altera-gsrd-image includes a full-featured set of packages:

• initramfs-altera
• kernel-modules
• netbase busybox
• base-passwd
• base-files
• tinylogin sysvinit
• initscripts
• e2fsprogs
• mtd-utils
• gdb
• gdbserver
• bash
• strace
• openssh
• openssl
• elfutils
• sysfsutils
• usbutils
• dtc
• gawk
• ethtool
• grep
• lighttpd
• iputils
• make
• pciutils
• portmap
• sed
• setserial
• wget
• autoconf
• diffutils
• perl
• minicom
• i2c-tools
• iptables
• oprofile
• net-tools
• gator
• openssh-sftp-server
• gsrd-altera
• pio-interrupt-altera
• initscripts-altera
• util-linux

How to add packages to the root file system?

To add a package to the root filesystem, open the conf/local.conf file and add then to the IMAGE_INSTALL_append variable. The following demonstrates how to add mtd-utils. NOTE: The space before the package name is very necessary! Without it the package name you provide will be appended to the end of the name of the last default package.

IMAGE_INSTALL_append = " mtd-utils"

How to create a new package in Yocto

The basis for creating a new yocto recipe can be found on the yocto project website: https://wiki.yoctoproject.org/wiki/How_do_I

How to specify the geometry of a NAND device

You can specify the option to be passed to mkfs.jffs2 by adding the following line to your conf/local.conf file. By default, eraseblock=0x40000

EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x10000 -\u2013pagesize=0x100"

Where are the binaries once the sources are built?

After running bitbake you can find the results within the tmp/deploy/images directory. A link is created to the most recent build. For instance, zImage may link to zImage-1.0-r1-socfpga_cyclone5-20130912183930.bin if that was the most recently built zImage.

Where do I find additional documentation on Yocto?

Yocto is a very large and active project. More documentation is available from these sites:

• Yocto Project: http://www.yoctoproject.org/
• Yocto wiki: https://wiki.yoctoproject.org/wiki/Main_Page
• Yocto Project's documentation: http://www.yoctoproject.org/documentation
• Yocto Quick Start Guide: https://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html
• Yocto Distribution Support: https://wiki.yoctoproject.org/wiki/Distribution_Support

Acronyms

Acronym	Meaning
OE	Open Embedded
OS	Operating System
SOCFPGA	Altera's family of SOC's combining ARM CPU's with FPGA's
SOC	System On Chip
FPGA	Field Programmable Gate Array
ARM	British Company that design the ARM CPU
CPU	Central Processing Unit
BSP	Board Support Package