Building Yocto or Angstrom for SoCFPGA

Build and customize Angstrom or Yocto based linux

General Info

Both Angstrom and Yocto are OpenEmbedded based distributions or distribution builders. Documentation for Angstrom and Yocto can be found in their respective sites.

• Angstrom Distribution
• Yocto Project

Having the same underlying build tools, both rely on Python based recipes enabled through layers. Layers consist of a directory, configuration files, and recipes for building various images such as the linux kernel for example. Recipes consist of bitbake files ( bb extension ). The recipes can easily be extended of modified using bbappend files making the build environment highly configurable and easily extended.

For SoCFPGA support, a meta-altera layer exists enabling support of Intel SoC FPGA platforms. The meta-altera layer used in this guide is the public kraj/meta-altera layer which can be found here:

• kraj/meta-altera

Prerequisites

Yocto and Angstrom share the same host requirements. Please review the latest Yocto documentation for Build host requirements.

• Yocto 2.7 Warrior Build Host Requirements

Furthermore, Yocto provides extensive information in it's documentation, please review.

• Yocto Project Docs

And this is a good read as well

• What I wish i'd known

Status of kraj/meta-altera

Support is currently available for Cyclone5/Arria5, Arria10, and Stratix10. With the exception of Stratix10, the layer uses a vanilla mainline u-boot for the bootloader. Stratix10 uses mainline u-boot with some patches but this is not officially supported although tested and working. The default when building an image is to output a wic file, which is an SDCard image. It includes the kernel, bootloaders, devicetrees, and root file system but at this time it does not include any FPGA images. For Arria10, you are required it add at a minimum a FIT image containing the periphery FPGA image as described in the u-boot documentation here.

The meta-altera machine configurations currently target the Intel SoC development kits as follows:

MACHINE	Development Kit	Link to kit
stratix10	Stratix 10 SX SoC Development Kit	S10SoCDK
arria10	Intel® Arria® 10 SoC Development Kit	A10SocDK
arria5	Arria® V SoC Development Kit	A5SoCDK
cyclone5	Cyclone® V SoC Development Kit	C5SoCDK
10m50	Intel® MAX® 10 FPGA Development Kit	10M50DK

Selecting kernel versions in meta-altera

The meta-altera layer provides for "linux-altera", "linux-altera-ltsi", and "linux-altera-ltsi-rt" kernel versions. The currently supported versions are:

Kernel	Version
linux-altera	5.0
linux-altera-ltsi	4.14.73
linux-altera-ltsi-rt	4.14.73

Please note that only the latest versions of the three kernel types are supported. It is strongly recommended you use the latest versions provided to ensure all known bugs are addressed.

There are a few ways of selecting the kernel version, my preference is to set the PREFERRED_PROVIDER and PREFERRED_VERSION in conf/local.conf. If PREFERRED_VERSION is not specified, bitbake will default to the newest version.

For example:

PREFERRED_PROVIDER_virtual/kernel = "linux-altera"
PREFERRED_VERSION_linux-altera = "5.0%"

or

PREFERRED_PROVIDER_virtual/kernel = "linux-altera-ltsi"
PREFERRED_VERSION_linux-altera-ltsi = "4.14.73%"

or

PREFERRED_PROVIDER_virtual/kernel = "linux-altera-ltsi-rt"
PREFERRED_VERSION_linux-altera-ltsi-rt = "4.14.73%"

Note that the % in the PREFERRED_VERSION is important!

Alternatively, you can use environment variables to specify the kernel provider, but note that setting the PREFERRED_PROVIDER has precedence.

For example:

$ export KERNEL_PROVIDER="linux-altera"
$ export BB_ENV_EXTRAWHITE="${BB_ENV_EXTRAWHITE} KERNEL_PROVIDER"

With the above, you can still set the PREFERRED_VERSION.

Selecting the u-boot configuration in meta-altera

The u-boot build mechanism allows for setting a u-boot configuration. These are represented in the u-boot source as various u-boot defconfigs. The UBOOT_CONFIG variable can be set in your build to override the default configuration. Current supported u-boot configurations are:

u-boot configuration	u-boot defconfig	Device
cyclone5-socdk	socfpga_cyclone5_defconfig	cyclone5
de0-nano-soc	socfpga_de0_nano_soc_defconfig	cyclone5
mcvevk	socfpga_mcvevk_defconfig	cyclone5
sockit	socfpga_sockit_defconfig	cyclone5
socrates	socfpga_socrates_defconfig	cyclone5
sr1500	socfpga_sr1500_defconfig	cyclone5
arria5-socdk	socfpga_arria5_defconfig	arria5
arria10-socdk	socfpga_arria10_defconfig	arria10
arria10-socdk-nand	socfpga_arria10_nand_defconfig	arria10
arria10-socdk-qspi	socfpga_arria10_qspi_defconfig	arria10
stratix10-socdk	socfpga_stratix10_defconfig	stratix10

Working with wic files

The wic configuration files for the devices supported in meta-altera are located in the wic folder. These are an example, and users should devise their own wks files to meet their needs. One common issue is adding files to the FAT partition in the wic image. This can be accomplished by using the IMAGE_BOOT_FILES variable. A common file needed is the FPGA configuration files:

• IMAGE_BOOT_FILES .= " my_file.rbf "

Another common issue with the wic image is the size of the rootfs. It is often necessary to add unused space to the root image.

To add a fixed amount of room:

• IMAGE_ROOTFS_EXTRA_SPACE = "524288"

Another option is to use IMAGE_OVERHEAD_FACTOR which takes the base image size and increases it my this factor.

• IMAGE_OVERHEAD_FACTOR = "1.6"

The output wic file is a full sdcard image and can be placed on an sdcard using windows diskimager or the linux dd utility:

For example: WARNING, DO NOT JUST COPY AND PASTE!!!

$ dd if=console-image-stratix10.wic of=/dev/mmcblk0 bs=1M

Angstrom

Introduction

Angstrom is a linux distribution and build infrastructure that includes a collection of layers enabling broad support for devices and software packages. One feature is support for opkg and binary feeds allowing you to run time install packages on your target. The current release of Angstrom is 2018.12 which is compatible with Yocto 2.6 Thud. An overview of the build process is available in the angstrom-manifest git repo.

• https://github.com/Angstrom-distribution/angstrom-manifest

Known Issues

Booting Angstrom over NFS

Booting Angstrom over NFS requires a change to the connman startup script connman.service (in /lib/systemd/system). The daemon should be called as follows:

ExecStart=/usr/sbin/connmand -n -I ethX

if you plan to mount the Angstrom RFS over NFS, please make sure to update the connman service script first. Otherwise, ethX gets reset and the NFS connection is lost. ethX corresponds to the Ethernet interface used when mounting a RFS over NFS. Usually this is eth0, but could be any Ethernet interface supported and available in a particular application. This could be the case if using a soft Ethernet controller configured into the FPGA such as the Altera Triple Speed Ethernet controller.

Login via SSH fails

There appears to be an issue with the default PAM configuration that causes SSH logins to fail. Revert the sshd_config to not use PAM, and allow root login should you desire.

To do this, edit /etc/ssh/sshd_config

• Change UsePAM yes to UsePAM no
• Optionally uncomment → PermitRootLogin yes

Prerequisites

• You will need to install the repo tool, please see the appendix.
• You will need to have a linux system suitable for the build as described in the Overview.

Angstrom setup

We need to clone the angstrom-manifest, and setup the some layers

$ mkdir angstrom-build
$ cd angstrom-build
$ repo init -u https://github.com/Angstrom-distribution/angstrom-manifest -b angstrom-v2018.12-thud

At this point we are ready to proceed, however if you want to add to or customize the layers used in the angstrom build, now is the time. To do so we can make our own manifest snippets, for example, should we want to override the meta-altera layer with our own fork, we would:

NB: Only an example, do not copy blindly.

$ cd .repo
$ mkdir local_manifests
$ cd ../
$ vi .repo/local_manifests/altera.xml

Add the following to altera.xml

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
        <remove-project name="kraj/meta-altera" />
        <project remote="github"  name="dwesterg/meta-altera" path="layers/meta-altera" revision="thud"/>
</manifest>

This removes meta-altera from the default manifest, and overrides it with my own fork. For reference on manifests and the repo tool, look at the following.

• https://source.android.com/setup/develop/repo
• https://gerrit.googlesource.com/git-repo/+/master/docs/manifest-format.md

After you are done modifying or adding layers, we are just about ready to build. Run the following to fetch all of the layers in the manifest

$ repo sync
Fetching project meta-intel
Fetching project koenkooi/meta-dominion
Fetching project meta-freescale
Fetching project koenkooi/meta-photography
...

Angstrom machine and kernel configuration

We can build for any of the MACHINE configurations supported in the meta-altera layer by running one of the following commands:

MACHINE=stratix10 . ./setup-environment

MACHINE=arria10 . ./setup-environment

MACHINE=arria5 . ./setup-environment

MACHINE=cyclone5 . ./setup-environment

The MACHINE variable obviously selects the machine you intend to build for. You can build for any supported machine in the same directory, if the build can be re-used (c5 / a5 / a10) it will be.

For this example, we will build for Stratix10.

$ MACHINE=stratix10 . ./setup-environment 
linking to python2
Fetching project meta-intel
Fetching project koenkooi/meta-dominion
Fetching project meta-freescale
Fetching project koenkooi/meta-photography
Fetching project meta-xilinx
Fetching projects:   5% (2/35)  Fetching project Freescale/meta-freescale-3rdparty
Fetching projects:   8% (3/35)  Fetching project openembedded/meta-linaro
Fetching projects:  11% (4/35)  Fetching project koenkooi/meta-beagleboard
Fetching projects:  14% (5/35)  Fetching project meta-qt4
Fetching projects:  17% (6/35)  Fetching project shr-distribution/meta-smartphone
Fetching projects:  20% (7/35)  Fetching project meta-mono
Fetching projects:  22% (8/35)  Fetching project koenkooi/meta-edison
Fetching projects:  25% (9/35)  Fetching project agherzan/meta-raspberrypi
Fetching projects:  28% (10/35)  Fetching project kraj/meta-nslu2
Fetching projects:  31% (11/35)  Fetching project linux-sunxi/meta-sunxi
Fetching projects:  34% (12/35)  Fetching project linux4sam/meta-atmel
Fetching projects:  37% (13/35)  Fetching project OSSystems/meta-browser
Fetching projects:  40% (14/35)  Fetching project ndechesne/meta-qcom
Fetching projects:  42% (15/35)  Fetching project agherzan/meta-chip
Fetching projects:  45% (16/35)  Fetching project koenkooi/meta-kodi
Fetching projects:  48% (17/35)  Fetching project koenkooi/meta-uav
Fetching projects:  51% (18/35)  Fetching project schnitzeltony/meta-gumstix-community
Fetching projects:  54% (19/35)  Fetching project openembedded/bitbake
Fetching projects:  57% (20/35)  Fetching project meta-maker
Fetching projects:  60% (21/35)  Fetching project kraj/meta-altera
Fetching projects:  62% (22/35)  Fetching project openembedded/meta-openembedded
Fetching projects:  65% (23/35)  Fetching project 96boards/meta-96boards
Fetching projects:  68% (24/35)  Fetching project meta-java
Fetching projects:  71% (25/35)  Fetching project meta-ti
Fetching projects:  74% (26/35)  Fetching project meta-qt5/meta-qt5
Fetching projects:  77% (27/35)  Fetching project openembedded/openembedded-core
Fetching projects:  80% (28/35)  Fetching project superna9999/meta-meson
Fetching projects:  82% (29/35)  Fetching project openembedded/meta-backports
Fetching projects:  85% (30/35)  Fetching project bmwcarit/meta-ros
From https://github.com/openembedded/openembedded-core
   8f596d485b..83a36fb20f  master     -> github/master
Fetching projects:  88% (31/35)  Fetching project Angstrom-distribution/meta-angstrom
Fetching projects: 100% (35/35), done.  

Welcome to Ångström ( A Yocto Project Compatible Distribution )

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/

Your build environment has been configured with:

    MACHINE=stratix10
    SDKMACHINE=x86_64
    DISTRO=angstrom

You can now run 'bitbake <target>'

Some of common targets are:
    console-image
    systemd-gnome-image
    xfce-nm-image
    development-xfce-image
    development-gnome-image
$ 

Next we want to setup the kernel version we prefer. Each machine configuration sets up a default kernel provider. These can be found in the meta-altera layer under conf/machine. The stratix10.conf defaults to the "linux-altera" kernel provider. Refer to the Selecting kernel versions in meta-altera section on how to specify a kernel version.

Angstrom Kernel configuration

It is possible to make kernel configuration changes using Angstrom and the kernel's menuconfig.

bitbake -c menuconfig virtual/kernel

The above opens the standard linux configuration window, and has already applied the default kernel configuration for your machine.

bitbake -c diffconfig virtual/kernel

In the output for the diffconfig command, a path to a fragment.cfg is provided. This contains the differences between the default configuration and your configuration. The cfg file can be used when creating your own layer to modify the default kernel configuration.

Building the Angstrom image

To build:

bitbake angstrom-image

On my moderate machine, the build process takes roughly 1.5 hours.

Once complete, the output from the build can be found in ${ANGSTROM_TOP}/deploy/glibc/images/${MACHINE}

$ ls
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.cpio
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.ext3
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.manifest
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.tar.gz
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.tar.xz
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.rootfs.wic
Angstrom-base-image-glibc-ipk-v2018.12-stratix10.testdata.json
base-image-stratix10.cpio
base-image-stratix10.ext3
base-image-stratix10.manifest
base-image-stratix10.tar.gz
base-image-stratix10.tar.xz
base-image-stratix10.testdata.json
base-image-stratix10.wic
Image
Image--5.0+git0+0ac4bbee4a-r0.2-stratix10-20190601173120.bin
Image-stratix10.bin
modules--5.0+git0+0ac4bbee4a-r0.2-stratix10-20190601173120.tgz
modules-stratix10.tgz
socfpga_stratix10_socdk--5.0+git0+0ac4bbee4a-r0.2-stratix10-20190601173120.dtb
socfpga_stratix10_socdk.dtb
socfpga_stratix10_socdk-stratix10.dtb
sshd_config
u-boot-dtb.img
u-boot-dtb.img-stratix10-socdk
u-boot-spl-dtb.hex
u-boot-spl-dtb.hex-stratix10
u-boot-spl-dtb.hex-stratix10-socdk
u-boot-spl-dtb.hex-stratix10-stratix10-socdk
u-boot-spl-dtb.hex-stratix10-v2019.07+gitAUTOINC+7e090b466c-2-stratix10-socdk-v2019.07+gitAUTOINC+7e090b466c-2
u-boot-stratix10.img
u-boot-stratix10.img-stratix10-socdk
u-boot-stratix10-socdk-v2019.07+gitAUTOINC+7e090b466c-2.img

Please refer to Workingwithwicfiles on using wic images.

Interacting with the package manager

The Angstrom distribution relies on 'opkg' as the package manager

Here are a few useful commands:

# list available packages
$ opkg list

# search for a particular package, e.g. gcc
$ opkg list | grep gcc

# install a package
$opkg install gcc

# list the installed packages
$ opkg list-installed

# getting updated information from the package feeds
$ opkg update

This is just a quick introduction to opkg.

Yocto

Introduction

Unlike Angtrom, Yocto's Poky does automatically include a large number of layers. For many packages and bsps you will need to add layers individually. This is very flexible, but obviously requires more initial configuration.

The current release of Yocto Poky is 2.7 Warrior, in this guide we will add the meta-altera layer and build an image for Stratix10.

This is just an overview, please review the documentation on yoctoproject.org for complete instructions.

Known Issues

Warrior does not support Fedora 30 at this time due to glibc differences in the uninative download. To avoid this, simply disable uninative by adding the following to your local.conf

• INHERIT_remove = "uninative"

Setup Yocto Poky & other layers

First we need to checkout all of the relevant repositories

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

Should you need any other layers, make sure to look at the layer index.

• Layer Index

Prepare and configure Yocto Poky

Here we source the oe setup script, and configure the local.conf and bblayers.conf

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

You should see something like

### Shell environment set up for builds. ###

You can now run 'bitbake <target>'

Common targets are:
    core-image-minimal
    core-image-sato
    meta-toolchain
    meta-ide-support

You can also run generated qemu images with a command like 'runqemu qemux86'

Configure bblayers.conf

vi conf/bblayers.conf

Change the file from (and yes, the path should reflect the path to your source files)

# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  /data/yocto-builds/build/poky/meta \
  /data/yocto-builds/build/poky/meta-poky \
  /data/yocto-builds/build/poky/meta-yocto-bsp \
  "

to

# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  /data/yocto-builds/build/poky/meta \
  /data/yocto-builds/build/poky/meta-poky \
  /data/yocto-builds/build/poky/meta-yocto-bsp \
  ${TOPDIR}/../meta-altera \
  "

Configure local.conf

We can now setup the build for the device we want to target and make any changes we think necessary, such as setting IMAGE_ROOTFS_EXTRA_SPACE or adding stuff to the image we intend to build using IMAGE_INSTALL_append.

vi conf/local.conf

Add

MACHINE = "stratix10"

or specify your intended target (arria10 / arria5 / cyclone5)

We can also specify the kernel type and version to build as described in the overview.

Building a Yocto Image

As with Angstrom, you do have the option of building individual recipes, such as the kernel or bootloader. We will in this example just build a wic image as all of the dependencies will be built along with it.

bitbake core-image-minimal

WARNING: Host distribution "fedora-30" has not been validated with this version of the build system; you may possibly experience unexpected failures. It is recommended that you use a tested distribution.
Loading cache: 100% |########################################################################################################################| Time: 0:00:00
Loaded 3015 entries from dependency cache.
Parsing recipes: 100% |######################################################################################################################| Time: 0:00:01
Parsing of 1978 .bb files complete (1973 cached, 5 parsed). 3017 targets, 108 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION           = "1.42.0"
BUILD_SYS            = "x86_64-linux"
NATIVELSBSTRING      = "fedora-30"
TARGET_SYS           = "aarch64-poky-linux"
MACHINE              = "stratix10"
DISTRO               = "poky"
DISTRO_VERSION       = "2.7"
TUNE_FEATURES        = "aarch64 armv8a crc"
TARGET_FPU           = ""
meta                 
meta-poky            
meta-yocto-bsp       = "warrior:f2b442c5c8e3925a4d3fc9693f1e47863dade2a9"
meta-altera          = "master:f8618243b28fea3490b678ed3d773de8bc1e5f1e"
meta-python          
meta-oe              = "warrior:6fa72d587aab8e9d56d67a2552eb9cfbe25c86d2"

After a lengthy time, the images will be available in tmp/deploy/images/${MACHINE}

ls tmp/deploy/images/stratix10/
core-image-minimal-stratix10-20190605141322.rootfs.cpio
core-image-minimal-stratix10-20190605141322.rootfs.ext3
core-image-minimal-stratix10-20190605141322.rootfs.manifest
core-image-minimal-stratix10-20190605141322.rootfs.tar.gz
core-image-minimal-stratix10-20190605141322.rootfs.wic
core-image-minimal-stratix10-20190605141322.testdata.json
core-image-minimal-stratix10.cpio
core-image-minimal-stratix10.ext3
core-image-minimal-stratix10.manifest
core-image-minimal-stratix10.tar.gz
core-image-minimal-stratix10.testdata.json
core-image-minimal-stratix10.wic
Image
Image--5.0+git0+0ac4bbee4a-r0-stratix10-20190525173140.bin
Image-stratix10.bin
modules--5.0+git0+0ac4bbee4a-r0-stratix10-20190525173140.tgz
modules-stratix10.tgz
socfpga_stratix10_socdk--5.0+git0+0ac4bbee4a-r0-stratix10-20190525173140.dtb
socfpga_stratix10_socdk.dtb
socfpga_stratix10_socdk-stratix10.dtb
u-boot-dtb.img
u-boot-dtb.img-stratix10-socdk
u-boot-spl-dtb.hex
u-boot-spl-dtb.hex-stratix10
u-boot-spl-dtb.hex-stratix10-socdk
u-boot-spl-dtb.hex-stratix10-stratix10-socdk
u-boot-spl-dtb.hex-stratix10-v2019.07+gitAUTOINC+7e090b466c-2-stratix10-socdk-v2019.07+gitAUTOINC+7e090b466c-2
u-boot-stratix10.img
u-boot-stratix10.img-stratix10-socdk
u-boot-stratix10-socdk-v2019.07+gitAUTOINC+7e090b466c-2.img

Please refer to Working with wic files on using wic images.

Customizing Angstrom/Yocto via a meta layer

WORK IN PROGRESS

Creating your own meta layer

Defining your own Machine

Customizing the kernel using bbappends

Customizing u-boot (adding your own machine conf, customizing for fpga image)

Creating your own image

Devtool

https://wiki.yoctoproject.org/wiki/TipsAndTricks/Patching_the_source_for_a_recipe https://www.youtube.com/watch?v=CiD7rB35CRE http://events17.linuxfoundation.org/sites/events/files/slides/Kernel-Tutorial.pdf

https://www.linux.com/blog/2018/4/real-world-build-tips-yocto