BSP meta-layer for Intel (ALTERA) SoC-FPGAs (SoCFPGAs) and the Yocto Project

With this layer the board support package (BSP) for ARM based Intel (ALTERA) SoC-FPGAs (SoCFPGA) is added to the Yocto Project.
It can bring with the rstools useful tools to interact with the FPGA fabric (e.g. Changing the FPGA configuration or accessing all ARM AXI Bride interfaces).
In addition, is the ARM Development Studio (DS-5) Streamline Server gator included.

Usually the Yocto Project can generate all required components (rootfs, device tree, bootloaders,...) to boot up a final embedded Linux. But this is not compatible with Intel's Boot flow. This Bootflow uses the Intel Embedded Design Suite (EDS) to build the device tree and all necessary bootloaders.

For that reason, I designed a version that is compatible with Intel's development tools.
This includes the board specific u-boot- and device tree-generation and the support for only the .tar.gz-file type for the rootfs.

I used this layer to build rsyocto, an open source embedded Linux Distribution for Intel SoC-FPGAs, by myself. The flexibility of my own rsyocto build system allows you to use it for your own projects with your custom embedded Linux.

For instance with a single Linux shell command (FPGA-writeConfig) of the rstools it is possible to change FPGA configuration of a Intel Cyclone V SoC-FPGA:

More rstools examples are available here inside my rsyocto guide.

Note: Right now only are the rstools for the Intel Cyclone V- and Intel Arria 10 SX- SoC-FPGA available.

Supported Device families

Device Family	Architecture	Machine Name
Intel (ALTERA) Cylone V SoC-FPGA	ARMv7A	MACHINE ="cyclone5"
Intel (ALTERA) Arria 10 SoC-FPGA	ARMv7A	MACHINE ="arria10"

Linux Kernel Types

Linux Version Name	Version Type	Supported Linux Kernel Versions
"linux-altera"	Regular Linux Version	`5.8`, `6.0`, `6.1`, `6.2`, `6.5`, `6.6`, `6.7`
"linux-altera-lts"	Long term stable Linux Version (LTS)	`5.4.54`,`5.10.60`,`5.10.100`, `5.15.70`, `5.15.80`, `5.15.90`, `5.15.100`, `6.1.20`, `6.1.38`, `6.1.55`, `6.1.68`

The Linux Kernel source code is available on the official Intel (ALTERA) repository.

List of rstools to interact with the FPGA-fabric

Linux Command Name	Description	CV	A10	Bitbake value
`FPGA-status`	Reading the Status of the FPGA fabric	✔️	✔️	statusfpga
`FPGA-readMSEL`	Reading the Configuration mode of the FPGA (selected with the MSEL-Bit Switch)	✔️	✔️	mselfpga
`FPGA-dumpbridge`	Reading a address span from an address of an AXI Bridge interface or SDRAM	✔️	❌	dumpbridge
`FPGA-resetFabric`	Resetting the FPGA fabric (remove the FPGA running configuration)	✔️	❌	resetfabricfpga
`FPGA-writeConfig`	Writing a new FPGA configuration with a configuration file	✔️	❌	writeconfigfpga
`FPGA-readBridge`	*Reading from an address of an AXI Bridge interface (Lightweight HPS2FPGA* or HPS2FPGA) or form the MPU Address space**	✔️	✔️	readbridgesfpga
`FPGA-writeBridge`	*Writing to an address of an AXI Bridge interface (Lightweight HPS2FPGA* or HPS2FPGA) or form the MPU Address space**	✔️	✔️	writebridgefpga
`FPGA-gpiRead`	Reading the 32 Bit direct access general purpose input Register (GPI) (written by the FPGA)	✔️	❌	readfgpipga
`FPGA-gpoWrite`	Writing the 32 Bit direct access general purpose output Register (GPO)	✔️	❌	writegpofpga

The source code of the rstools is available here: For the Intel Cyclone V SoC-FPGA and For the Intel Arria 10 SoC-FPGA

List of available additional components

Component Name	Description	Bitbake value
`gator`	*ARM Development Studio (DS-5) Streamline server*	gator
`initscript`	Enables to execute various init scripts during Linux booting at different booting levels	initscript

A Linux Kernel Configuration with an appropriate configuration to enable all ARM Core-Sight Debugging features for ARM Streamline will be automatically loaded.

Choose your preferred ARM Development Studio (DS-5) Streamline server version

Gator Version	Compatible ARM Streamline Version	Expression
`8.6.0`	`Streamline 8.6.0`	PREFERRED_VERSION:gator = "8.6.0"
`8.0.0`	`Streamline 8.0.0`	PREFERRED_VERSION:gator = "8.0.0"
`7.8.0`	`Streamline 7.8.0`	PREFERRED_VERSION:gator = "7.8.0"

Tested Development Machine Setup

OS
- Ubuntu 20.04 LTS
- Ubuntu 24.04 LTS
Yocto Project Releases
- scarthgap (5.0)

Note: Select the dedicated branch for the Yocto Project Release you want to use in this repository.

Getting started with the Yocto Project and use of this BSP-layer

The following step by step guide shows how to use this layer to build a Yocto-based Linux System for an Intel SoC-FPGA:

Step: Install the latest Version of the OpenEmbedded Yocto Project

As a Building machine use regular Ubuntu-Linux or CentOS Linux running as a Virtual Machine (VM)

Required components for the Yocto Project with Ubuntu Linux:

 sudo apt-get -y install gawk wget libgmp3-dev libmpc-dev \
 git diffstat unzip texinfo gcc-multilib build-essential \
 chrpath socat xterm libsdl2-image-2.0-0 u-boot-tools \
 python3 python3-pip python3-pexpect \
 python3-git python3-jinja2 libncurses-dev zstd lz4

Set local settings

 sudo locale-gen en_US.UTF-8
 export LANG=en_US.UTF-8
 export LC_ALL=en_US.UTF-8

Optional: Ubuntu Linux for usage of the Arm Development Studio (DS-5)

 sudo apt-get install libncurses5
 sudo apt-get install zlib1g:i386
 
 wget http://archive.ubuntu.com/ubuntu/pool/main/i/icu/libicu60_60.2-3ubuntu3_amd64.deb
 sudo apt install ./libicu60_60.2-3ubuntu3_amd64.deb
 
 wget http://de.archive.ubuntu.com/ubuntu/pool/universe/w/webkitgtk/libjavascriptcoregtk-1.0-0_2.4.11-3ubuntu3_amd64.deb
 sudo apt install ./libjavascriptcoregtk-1.0-0_2.4.11-3ubuntu3_amd64.deb
 
 wget http://security.ubuntu.com/ubuntu/pool/universe/w/webkitgtk/libwebkitgtk-1.0-0_2.4.11-3ubuntu3_amd64.deb
 sudo apt install ./libwebkitgtk-1.0-0_2.4.11-3ubuntu3_amd64.deb
 
 sudo apt-get install -y libc6-armel-cross libc6-dev-armel-cross binutils-arm-linux-gnueabi libncurses5-dev build-essential bison flex libssl-dev bc
 
 sudo apt-get install -y gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf  gcc-arm-linux-gnueabi g++-arm-linux-gnueabi

Check your git version (it should be 2.24+)
```
 git --version
```
Check your gcc version (it should be >13.2.0)
```
 gcc --version
```

Install the Yocto Project itself in Release 5.0 "scarthgap"

 cd && git clone -b scarthgap git://git.yoctoproject.org/poky.git

Install the OpenEmbedded SDK Standalone Version

cd ~/poky && wget https://downloads.yoctoproject.org/releases/yocto/yocto-5.0/buildtools/x86_64-buildtools-nativesdk-standalone-5.0.sh && sh x86_64-buildtools-nativesdk-standalone-5.0.sh

Run the SDK environment script as shown in the previous command, e.g.:
```
source /opt/poky/5.0/environment-setup-x86_64-pokysdk-linux
```

Step: Download this BSP-layer

cd poky/ && git clone https://github.com/robseb/meta-intelfpga.git

Step: Run the bitbake initialization script
```
source oe-init-build-env
```
- Do not run this command or any other Yocto commands as root!
- Do not use the command: “sudo ./ oe-init-build-env”. With this line Bitbake crashes later during the build process without any traceable error message
- The script should create the folder: "/build"

Step: Add this BSP-layer to your Yocto Project solution

Open the "bblayers.conf"-file (poky/build/conf) with a text editor for example with MS Visual Studio Code:
```
 code conf/bblayers.conf
```
Add the following line to this file to include the BSP-layer:
```
 /home/vm/poky/meta-intelfpga \
```
- Note: Replace the user name "vm" with your user name

Now should the "bblayers.conf"-file look like this:

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

 BBPATH = "${TOPDIR}"
 BBFILES ?= ""
 BBLAYERS ?= " \
   /home/vm/poky/meta \
   /home/vm/poky/meta-poky \
   /home/vm/poky/meta-yocto-bsp\
   /home/vm/poky/meta-intelfpga \
 "

Step: Configure the machine type and Linux Version
- Open the "local.conf"-file (poky/build/conf) with a text editor, for example with MS Visual Studio Code:
```
 code conf/local.conf
```
- Select your Intel SoC-FPGA family by adding the value "MACHINE" to this configuration file
  - For the different devices use string of the table above
  - For example, for an Intel Cyclone V SoC-FPGA add following to this file:
```
 MACHINE ="cyclone5"
```
  - Be sure that default "qwmux86-64" is removed
```
 # MACHINE ??= "qemux86-64"
```
- Select the Linux Kernel type
  - If you want to use the regular ALTERA socfpga-Linux Kernel add the line above to the "local.conf"-file:
```
 PREFERRED_PROVIDER_virtual/kernel = "linux-altera"
```
  - If you want the long term stable (LTSI) ALTERA socfpga-Linux Kernel use this line:
```
 PREFERRED_PROVIDER_virtual/kernel = "linux-altera-lts"
```
- Select the Linux Kernel Version
  - With following code line it is possible to select the preferred Linux Kernel Version (here with Version 6.1)
```
 PREFERRED_VERSION_linux-altera = "6.1%"
```
  - Alternatively, to select the Long term stable Linux Version (LTS) 6.1.68
```
 PREFERRED_VERSION_linux-altera = "6.1.68%"
```
  - All supported Linux Kernel versions are listed above
  - Add these two lines to the "local.conf"-file independent of your chosen machine
- Select the used CPU Version
  - For an Dual Core Intel (ALTERA) Cyclone V SoC-FPGA, Arria V SoC-FPGA or Arria 10 SoC-FPGA add the following line to the "local.conf"-file:
```
 DEFAULTTUNE = "cortexa9hf-neon"
```
  - This selects the ARMv7 Cortex-A9 dual core CPU with the NEON-Engine and a vector floating-point unit
- Save and close this file
Step: Check if your settings are vialed and executable
- The following shell-command lists all for this build used layers (executed inside poky/build/):
```
 bitbake-layers show-layers
```
  - If an error occured certainly something with the "local.conf- or "bblayers.conf"-file went wrong
- This command gives the used Linux Kernel Version
```
 bitbake --show-versions | grep linux  
```
Step: Optional: Change the Linux Kernel configuration
- To configure the Linux properly for a specific device family it is necessary to change the Linux Kernel configuration
- But for a first Yocto Project build is the Linux Kernel configured well enough
- Read and change the BSP-layer with "defcongig"
  - One part is configured by a "defconfig-file"
  - With that it is possible to enable or disabled every component, like for example ETHERNET, CAN, EXT2, HPS-Bridges and PCI
  - The following bitbake shell-command stores the "defconfig-file locally (executed inside poky/build/)
```
 bitbake -c savedefconfig virtual/kernel 
```
  - This command prints the directory of the saved file at the end
- Read and change the Linux Kernel with menueconfig
  - Use this command to start the "menueconfiguration"-tool:
```
 bitbake -c menuconfig -f virtual/kernel
```
  - A window like this should appear:
  - Here it is possible to change any kernel settings, ARM-Platform specific settings or enable or disable some peripherel components
  - The menueconfig configuration will be stored on the same directory as the defconfig
- To execute any BSP-layer change use the following command:
```
 bitbake -f -c compile virtual/kernel && bitbake -f -c deploy virtual/kernel
```
Step: Pre-install additional tools, like my rstools to interact with the FPGA configuration
- To pre-install addional components from this metal-layer it is only necessary to add the Bitbake value (as shown in the tables above) to the local.conf file
- For instance to pre-install the ARM Streamline gator Server insert the following line to local.conf (poky/build/conf/local.conf)
```
IMAGE_INSTALL:append = " gator "
```
- For installing all rstools use the following term
```
IMAGE_INSTALL:append = " mselfpga readbridgesfpga resetfabricfpga statusfpga writebridgefpga writeconfigfpga writegpofpga readfgpipga "
```
Step: Optional: Configure BusyBox
- BusyBox is a Linux Software that can bring the typical Linux Console envivonment as simple In-/Output interface to enable a basic user interaction
- The core-image-minimal image installs automatically BusyBox with a basic set of classical commands, such as ls, cd
- With the following term it will be enabled to add additional commands to BusyBox
```
bitbake -c menuconfig busybox
```
- If you want to save the busybox, the configuration file is written to a location as follows: ~/poky/build/tmp/work/cortexa9hf-neon-poky-linux-gnueabi/busybox/1.31.1-r0/busybox-1.31.1/
Step: Build the entire Yocto Project
- With this command the complete Yocto Project build process starts (executed inside poky/build/):
```
bitbake core-image-minimal
```
- This process can taken some time
- For an Intel Arria 10 SoC-FPGA the following start print should appear:
- This signaled that bitbake was able to decode the previously shown configuration
Step: Locate the final Kernel- and rootfs-File
- After a successful build the final compressed Linux Kernel file and the rootfs "tar.gz"- archive is stored here:
  - for an Intel Cyclone V SoC-FPGA:
```
 poky/build/tmp/delopy/images/cyclone5/
```
  - for an Intel Arria 10 SX SoC-FPGA:
```
 poky/build/tmp/delopy/images/arria10/
```
- The rootFs-file is called: core-image-minimal-cyclone5-<Date Code>.rootfs.tar.gz
- The Linux Kernel file is called: zImage-<...+>.bin
- Be sure that the files are not a Shortcut!
- In the case of an Intel Cyclone V SoC-FPGA, these two files are located here:

At this point a Linux for an Intel SoC-FPGA is generated. Unfortunately to boot this up also a Linux Device Tree, a primary- and secondary bootloader and for Intel Arria and Intel Stratix SoC-FPGAs two FPGA configuration files must be required.

Continuation

How to desgin the requiered bootloaders and the DeviceTree with Intel EDS ?

Inside my "Mapping HPS Peripherels, like I²C or CAN, over the FPGA fabric to FPGA I/O and using embedded Linux to control them"-guide I show that in details (see here).

How to embedded Python pip packages to a Yocto Project?

I also wrote a python script to pre-install Python pip (PyPI)- Packages within a final Yocto Project Linux Image automatically (see here).

How to bring the output files to a bootable image?

Build System: Use your Intel Quartus Prime FPGA project to create your own rsyocto with your FPGA Configuration

I designed a Python script that can automate the boot image desgin with a specifiable partition table. It can generate a bootable image file with Kernel-,bootloader- and user-files. With the flexibility of this script it is compatible with Intel SoC-EDS build flow for example it can pre-install FPGA configuration files.
Tools like "rufus" can write for instance a SD-card to enable the booting of a Linux Distribution. (see here LinuxBootImageGenerator).

The rsyocto build system can use the information provided by the Intel Quartus Prime FPGA project to compile and configure the bootloader (u-boot) to boot up an embedded Linux and to configure the FPGA Fabric with the Intel Quartus Prime FPGA project. The build system changes the rootfs of the embedded Linux und uses XML-files for configuration to automate every essential step to achieve a good experience of a modern Linux Distribution. It can directly use output files of the Yocto Project to generate a custom bootable Linux Distribution for Intel Cylone V- and Intel Arria 10 SX SoC-FPGAs. Please follow my detailed guide.