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.

How to setup the Yocto environment?

Setting up Yocto is a 3 step process. The first step is to install the Altera linux source release. It should be installed in a publicly accessible location, as this step can be shared by all users on the system (or on the filesystem if your company is using a network share). The default install location is /opt/altera-linux.

$ 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
$ sudo ./linux-socfpga-13.02-RC10-src.bsx

The second step is to install a local set of yocto recipes. This can 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 off of your home directory

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

The third step is to create a build directory. By keeping this seperate 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.

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

The above script performs 2 steps. First, it creates the new build directory using Alteras default configuration. Secondly, it sets some shell variables that are required for building. If you start a new shell you will need to run these commands to set these shell variables again. However, you will not have to specify the template configuration directory since your build directory already exists.

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

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 Altera's SOCFPGA Linux BSP with Yocto

In order to build u-boot from within the build directory:

$ bitbake virtual/bootloader

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 tmp/work/socfpga5xs1-poky-linux-gnueabi/linux-altera-3.7-r1/linux-altera-3.7. After modifying them you must force yocto to rebuild linux the Linux source, then tell it to rebuild the uImage file.

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

Although this will rebuild the uImage, 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 uImage CC="$CC" LD="$LD"

At this point new uImages will be available at arch/arm/boot/uImage

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

We include 2 root filesystems with our release- altera-image and altera-image-minimal. To build one, use the following syntax

   $ bitbake altera-image

Packages provided by Yocto

By default, altera-image-minimal includes the bare necessities for booting Linux. It includes the following

util-linux initramfs-altera kernel-modules busybox base-passwd base-files tinylogin sysvinit initscripts

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

util-linux 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 valgrind i2c-tools lttng-modules lttng-tools iptables oprofile net-tools gator openssh-sftp-server memtool

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 -–pagesize=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, uImage may link to uImage-3.7-r1-socfpga-cyclone5-20120919182707 if that was the most recently built uImage.

How to select the tool chain (gcc)

We have included the Linaro toolchain and selected it for building by default. However, you may wish to use the gcc built by Yocto instead. To do so, edit the file conf/local.conf in your build directory and remove or comment out the following lines:

#TCLIBC = "external-linaro-toolchain"
#TCMODE = "external-linaro"
#EXTERNAL_TOOLCHAIN = "/opt/altera/linaro/gcc-linaro-arm-linux-gnueabihf-4.7-2012.11-20121123_linux"

Where do I find additional documentation on Yocto?

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

• Yocto wiki: https://wiki.yoctoproject.org/wiki/Main_Page
• Yocto Project: http://www.yoctoproject.org/
• Yocto Project's documentation: http://www.yoctoproject.org/documentation

Links

Yocto

• Yocto project: http://www.yoctoproject.org/
• Yocto Quick Start Guide: https://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html
• Yocto Wiki: https://wiki.yoctoproject.org/wiki/Main_Page
• 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