Note: Support for Angstrom has been discontinued. Instead Yocto recipes are used to build the Linux rootfs. Refer to the GSRD (Golden System Reference Design) pages from https://www.rocketboards.org/foswiki/Main/GettingStarted for more details.

How to Build Angstrom for SoCFPGA

Introduction

Angstrom is a Linux distribution, targetting Embedded Systems. More information can be found on the Angstrom web site. Enabling Angstrom on SoCFPGA brings up the flexibility of a distribution: Instead of a fixed root file system as built with Yocto, the features of the file system can be changed at run time.

Preliminary note

Known Issues:

• 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.

Objective

Follow these steps to build the components required to run Angstrom on SoCFPGA:

• preloader
• boot loader
• kernel
• root file system

The steps to follow depends on the Angstrom version.

Prerequisites

1. ) You will need to install the repo tool, please see the appendix.
2. ) You will need to have a linux system suitable for the build. I recommend consulting the current Yocto Project [[https://www.yoctoproject.org/docs/][quickstart guide].

Angstrom v2017.12 / Yocto 2.4

These instructions will not go into the setup of the repo command, please look here.

Known Issues

Setup the build

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

$ mkdir angstrom-build
$ cd angstrom-build
$ repo init -u git://github.com/Angstrom-distribution/angstrom-manifest -b angstrom-v2017.12-rocko

We want to use the master branch of meta-altera, to do this we can add a local manifest. This is also where you can add your own layers.

$ 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="kraj/meta-altera" path="layers/meta-altera" revision="rocko"/>
</manifest>

Next we download all the layers and setup the build for out intended device.

$ repo sync
Fetching project meta-intel
Fetching project koenkooi/meta-dominion
Fetching project meta-freescale
Fetching project koenkooi/meta-photography
    %%  TToottaall        %%  RReecceeiivveedd  %%  XXffeerrdd    AAvveerraaggee  SSppeeeedd      TTiimmee        TTiimmee          TTiimmee    CCuurrrreenntt

                                                                 D lDolaoda d  U pUlpolaoadd      TToottaall     S pSepnetn t      L eLfetf t  Sp eSepde
ed
0    0     0      0  0      0    0      0  0      0    0      0      0      0      0   - -0: ----::---- :----: ----::---- :----: ----::---- : - -    0   0  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
   0  0        0  0      0  0        0  0      0  0        0  0          0  0     0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0

This goes on for a while …

For this example we are building for the Stratix10 device.

$ 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 environemnt 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
$ 

Note that to build for other devices, simple specify the correct machine type:

MACHINE=cyclone5 . ./setup-environment

or

MACHINE=arria5 . ./setup-environment

or

MACHINE=arria10 . ./setup-environment

It is perfectly acceptable to build for different machines in the same angstrom-manifest directory.

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. The meta-altera layer provides for "linux-altera", "linux-altera-ltsi", and "linux-altera-ltsi-rt". These currently are the 4.15, 4.9.78-ltsi, and 4.9.76-ltsi-rt kernels.

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 = "4.15%"

or

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

or

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

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.

How to build the root file system

Angstrom provides for a number of rootfs configurations, in the end you are likely to define your own. In this example, we will build a "smaller" rootfs from Angtrom, console-image. By default, building console image does not pull in the bootloader or kernel itself. However the Cyclone5/Arria5 and Stratix10 machine configurations specify wic as an output image type. Wic is a Yocto tool for building sdcard and HDD images, and wic for Cyclone5/Arria5 and Stratix10 adds dependencies for the bootloader and the kernel.

To build the rootfs:

bitbake console-image

Building and configuring the kernel

Should you need to customize the default kernel configuration for your machine (this is not necessary at all), it is possible to run the kernel's configuration menu.

bitbake -c menuconfig virtual/kernel

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

Setup Environment Menu

Changes made to the configuration can be captured using another bitbake command:

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.

To build the kernel

bitbake virtual/kernel

Note that if you do this AFTER building the rootfs, the wic image will not contain the latest kernel build. Simple rerun bitbake console-image and the wic image will be updated.

Where are the binaries once the build is finished?

The binaries can be found in ${ANGSTROM_TOP}/deploy/glibc/images/

Note that currently the Cyclone5/Arria5 and Stratix10 recipes include the generation of a wic file. A wic file is an SDCard image for the intended device. It includes the bootloader, kernel, and rootfs. Since the kernel, bootloader, and rootfs are dependencies of the wic image, building the rootfs will also build the kernel and bootloaders.

For this Stratix10 build, the output directory contains:

$ ls
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.cpio
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.ext3
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.manifest
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.tar.gz
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.tar.xz
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.rootfs.wic
Angstrom-console-image-glibc-ipk-v2017.12-stratix10.testdata.json
console-image-stratix10.cpio
console-image-stratix10.ext3
console-image-stratix10.manifest
console-image-stratix10.tar.gz
console-image-stratix10.tar.xz
console-image-stratix10.testdata.json
console-image-stratix10.wic
Image
Image--4.9.78-ltsi+git0+6fdee619e7-r0.2-socfpga_stratix10_socdk-20180227061157.dtb
Image--4.9.78-ltsi+git0+6fdee619e7-r0.2-stratix10-20180227061157.bin
Image-socfpga_stratix10_socdk.dtb
Image-stratix10.bin
modules--4.9.78-ltsi+git0+6fdee619e7-r0.2-stratix10-20180227061157.tgz
modules-stratix10.tgz
socfpga_stratix10_socdk.dtb
u-boot-dtb.img
u-boot-dtb.img-stratix10-socdk
u-boot-spl-dtb.bin
u-boot-spl-dtb.bin.ihex
u-boot-spl-dtb.bin.ihex-stratix10
u-boot-spl-dtb.bin.ihex-stratix10-socdk
u-boot-spl-dtb.bin.ihex-stratix10-stratix10-socdk
u-boot-spl-dtb.bin-stratix10
u-boot-spl-dtb.bin-stratix10-socdk
u-boot-spl-dtb.bin-stratix10-stratix10-socdk
u-boot-spl-dtb.bin-stratix10-v2017.09+gitAUTOINC+8807902b23-r0.ihex-stratix10-socdk-v2017.09+gitAUTOINC+8807902b23-r0
u-boot-spl-dtb.bin-stratix10-v2017.09+gitAUTOINC+8807902b23-r0-stratix10-socdk-v2017.09+gitAUTOINC+8807902b23-r0
u-boot-stratix10.img
u-boot-stratix10.img-stratix10-socdk
u-boot-stratix10-socdk-v2017.09+gitAUTOINC+8807902b23-r0.img

The wic file can simply be dd'ed to an sdcard.

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

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

Appendix

Installing the repo tool

$ mkdir ~/bin
$ PATH=~/bin:$PATH

$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

Please look here if you have any other issues.

Angstrom links

Please check out their web site and check their package feeds for the ARMv7 architecture.

Booting Angstrom

There is nothing special to do from a kernel command line point of view. Angstrom uses udev, so make sure your kernel configuration includes the following options:

      CONFIG_DEVTMPFS=y
      CONFIG_HOTPLUG=y
      CONFIG_INOTIFY_USER=y
      CONFIG_NET=y
      CONFIG_PROC_FS=y
      CONFIG_SIGNALFD=y
      CONFIG_SYSFS=y
      CONFIG_UEVENT_HELPER_PATH=""

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.

---