Create a custom BSP layer for Intel SoC or FPGA

It is possible to customize existing meta layers by creating an own meta layer with bitbake append files. In this description the meta layer meta-altera for Intel FPGA devices is used as reference.

For more informations about the OS used and the sources and versions of yocto project or meta-altera layer, see Yocto KICKstart#Used source files.

Initialize the environment

Before starting to create a custom meta layer, navigate to the yocto poky directory and initialize the environment with the following commands:

cd path/to/yocto/poky
source oe-init-build-env

Download required sources

Since the created meta-custom layer should depend on meta-altera, these sources files must be downloaded and added to the yocto project.

1. Navigate to yocto poky directory and download meta-altera layer:

   cd path/to/yocto/poky
   git clone -b dunfell https://github.com/kraj/meta-altera.git

2. Add meta-altera to yocto project with:

   cd path/to/yocto/poky/build
   bitbake-layers add-layer ./meta-altera

Create BSP layer

In this example, the created layer is named meta-custom. If you want to use a different name, just replace "custom".

1. Create own layer "meta-custom" with:

   bitbake-layers create-layer path/to/yocto/poky/meta-custom

2. The created layer contains a sample recipes folder, that can be removed:

   rm -rf path/to/yocto/poky/meta-custom/recipes-example

3. Make meta-custom dependent on meta-altera:

   sed -i '/LAYERDEPENDS_meta-custom/s/core/meta-altera/g' path/to/yocto/poky/meta-custom/conf/layer.conf 

4. Add the meta-custom layer to the yocto project with:

   bitbake-layers add-layer path/to/yocto/poky/meta-custom

Configure BSP Machine

In the machine configuration file, you can store general settings for the custom BSP layer, such as the version of u-boot or the linux kernel. Here, we will use the cyclone5 machine configuration file from the meta-altera layer as a template. For other machine configurations in the meta-altera layer, see meta-altera/conf/machine.

1. Download the cyclone5 machine configuration file to the meta-custom layer and rename it:

   mkdir -p path/to/yocto/poky/meta-custom/conf/machine
   cd path/to/yocto/poky/meta-custom/conf/machine
   wget https://github.com/kraj/meta-altera/raw/dunfell/conf/machine/cyclone5.conf
   mv cyclone5.conf custom.conf

2. Make the following changes to the content of custom.conf:

   1. Change the name in line 2 from 'cyclone5' to 'custom' and customize the variables UBOOT_EXTLINUX_DEFAULT_LABEL and UBOOT_EXTLINUX_MENU_DESCRIPTION_default:

      sed -i '/^#@NAME:/s/.*/#@NAME: custom/g' path/to/yocto/poky/meta-custom/conf/machine/custom.conf
      sed -i '/^UBOOT_EXTLINUX_DEFAULT_LABEL/s/".*"/"Cyclone5 custom SDMMC"/g' path/to/yocto/poky/meta-custom/conf/machine/custom.conf
      sed -i '/^UBOOT_EXTLINUX_MENU_DESCRIPTION_default/s/".*"/"Cyclone5 custom SDMMC"/g' path/to/yocto/poky/meta-custom/conf/machine/custom.conf

   2. The KMACHINE variable defines the MACHINE name, which is referenced in the build/conf/local.conf file. Redefine KMACHINE with your own MACHINE name:

      sed -i '/^KMACHINE/s/".*"/"custom"/g' path/to/yocto/poky/meta-custom/conf/machine/custom.conf

   3. For the linux kernel in the meta-altera layer it's required to define a the preferred provider and version in custom.conf (see Yocto KICKstart#Used source files for more information about the version used). Add the provider and version for linux kernel:

      echo -e '\nPREFERRED_PROVIDER_virtual/kernel = "linux-altera-lts"' >> path/to/yocto/poky/meta-custom/conf/machine/custom.conf 
      echo -e 'PREFERRED_VERSION_linux-altera-lts = "5.4%"' >> path/to/yocto/poky/meta-custom/conf/machine/custom.conf

   4. Set the preferred u-boot version for meta-altera in custom.conf (see Yocto KICKstart#Used source files for more information about the version used):

      echo -e '\nPREFERRED_VERSION_u-boot-socfpga = "v2021.04%"' >> path/to/yocto/poky/meta-custom/conf/machine/custom.conf

Other variables in the custom.conf file are changed or added at other points in this guide.

Add required parameters to local.conf

Before you start configuring the meta-custom layer, the MACHINE variable in the path/to/yocto/poky/build/conf/local.conf file must be set to the correct machine. The correct machine name is defined in the meta-custom/conf/machine/custom.conf file with the variable KMACHINE.
Remove the default value of the MACHINE variable in local.conf and add the new MACHINE 'custom':

sed -i '/^MACHINE/s/MACHINE/#MACHINE/g' path/to/yocto/poky/build/conf/local.conf
echo -e '\nMACHINE = "custom"' >> path/to/yocto/poky/build/conf/local.conf

Create workspace

The following command creates the workspace directory and adds it to bblayers.conf:

devtool create-workspace

Configure u-boot

Prepare u-boot configuration in workspace

To prepare the u-boot sources for modify the default configuration and create patches, do the following steps:

1. To set the correct default defconfig file for the u-boot, it is required to set the UBOOT_MACHINE variable in the meta-custom/conf/machine/custom.conf file. The defconfig file 'socfpga_cylcone5_defconfig' will be used as default u-boot configuration (see meta-altera/recipes-bsp/u-boot/u-boot-socfpga-common.inc for other Intel fpga defconfig files). If UBOOT_MACHINE has been defined, UBOOT_CONFIG is no longer needded.
   Remove the variable UBOOT_CONFIG and add UBOOT_MACHINE to meta-custom/conf/machine/custom.conf:

   sed -i '/^UBOOT_CONFIG/d' path/to/yocto/poky/meta-custom/conf/machine/custom.conf
   echo -e '\nUBOOT_MACHINE = "socfpga_cyclone5_defconfig"' >> path/to/yocto/poky/meta-custom/conf/machine/custom.conf
   

2. Run following command to prepare the workspace and fetch and unpack the sources:

   devtool modify u-boot-socfpga -O

Configure u-boot with menuconfig

To make changes to u-boot configuration, follow these steps:

1. Launch menuconfig with following command and make your changes:

   devtool menuconfig u-boot-socfpga

2. Exit and save your configuration. devtool-fragment.cfg will be created automatically.

Create patches for u-boot source files

Do following steps to create patches for u-boot source files:

1. Navigate to u-boot-socfpga in the workspace and add, modify or remove files:

   cd path/to/yocto/poky/build/workspace/sources/u-boot-socfpga

2. Run a build to test your changes:

   devtool build u-boot-socfpga

3. Add the changes made with:

   git add .

4. Commit your changes and add a short message. The message is used to name the patch file:

   git commit -m "<message>"

   If you get the following error message: "*** Please tell me who you are. Run ...", run this commands to define a name and email:

   git config --local user.email "oe.patch@oe"
   git config --local user.name "OpenEmbedded"

5. If you want to generate more patches, repeat steps 1 - 4, otherwise navigate back to the poky directory:

   cd path/to/yocto/poky

Create and update u-boot recipe bbappend

Add the devtool-fragment.cfg and the patches to the meta-custom layer with:

devtool update-recipe u-boot-socfpga -a path/to/yocto/poky/meta-custom -O

Configure linux kernel

Prepare linux kernel configuration in workspace

To prepare the linux kernel sources for modify the default configuration and create patches, do the following steps:

1. Run following command to prepare the workspace and fetch and unpack the sources:

   devtool modify linux-altera-lts -O

Configure linux kernel with menuconfig

To make changes to linux kernel configuration, follow these steps:

1. Launch menuconfig with following command and make your changes:

   devtool menuconfig linux-altera-lts

2. Exit and save your configuration. devtool-fragment.cfg will be created automatically.

Create patches for linux kernel source files

Do following steps to create patches for u-boot source files:

1. Navigate to linux-altera-lts in the workspace and add, modify or remove files:

   cd path/to/yocto/poky/build/workspace/sources/linux-altera-lts

2. Run a build to test your changes:

   devtool build linux-altera-lts

3. Add the changes made with:

   git add .

4. Commit your changes and add a short message. The message is used to name the patch file:

   git commit -m "<message>"

5. If you want to generate more patches, repeat step 1 - 4, otherwise navigate back to the poky directory:

   cd path/to/yocto/poky

Create and update linux kernel recipe bbappend

Add the devtool-fragment.cfg and the patches to the meta-custom layer with:

devtool update-recipe linux-altera-lts -a path/to/yocto/poky/meta-custom -O

Remove workspace

Remove the workspace from bblayers.conf and delete the workspace folder:

cd path/to/yocto/poky/build
bitbake-layers remove-layer workspace
rm -rf path/to/yocto/poky/build/workspace

Add custom files to meta layer

Add handoff files to u-boot

If you create a u-boot file for an Intel Cyclone V / Arria V with quartus version 20.1 you have to convert the handoff data into source code.

1. compile your quartus project

2. run the embedded command shell (Intel SoC EDS):

   ~/intelFPGA_lite/20.1/embedded/embedded_command_shell.sh

3. navigate to your quartus project directory and convert the handoff data into source code:

   cd path/to/quartus/project
   mkdir -p build
   bsp-create-settings --type spl --bsp-dir build \
   --preloader-settings-dir hps_isw_handoff/* \
   --settings build/settings.bsp

Next you have to run the qts_filter to take the sources from the handoff folder, format them and copy them to u-boot source code.

1. Fetch qts_filter.sh from github:

   wget https://raw.githubusercontent.com/altera-opensource/u-boot-socfpga/socfpga_v2021.04/arch/arm/mach-socfpga/qts-filter.sh

2. Run qts_filter for cyclone5 to format and copy the handoff files to custom meta layer:

   mkdir -p path/to/yocto/poky/meta-custom/recipes-bsp/u-boot/u-boot-socfpga/qts
   ./qts-filter.sh cyclone5 \
   				path/to/quartus/project \
   				path/to/quartus/project/build \
   				path/to/yocto/poky/meta-custom/recipes-bsp/u-boot/u-boot-socfpga/qts

3. Add the generated files to the u-boot bbappend file:

   cd  path/to/yocto/poky/meta-custom/recipes-bsp/u-boot
   gedit u-boot-socfpga*.bbappend

   Add qts_filter files and the following task to copy the qts_filter files to the correct place in u-boot sources during build image (if your are using another board, you have to adjust the file path):

   SRC_URI += "file://qts/iocsr_config.h \
   			file://qts/pinmux_config.h \
   			file://qts/pll_config.h \
   			file://qts/sdram_config.h \
   			"
   
   do_configure_prepend () {
   	install -m 0644 ${WORKDIR}/qts/iocsr_config.h ${S}/board/altera/cyclone5-socdk/qts
   	install -m 0644 ${WORKDIR}/qts/pinmux_config.h ${S}/board/altera/cyclone5-socdk/qts
   	install -m 0644 ${WORKDIR}/qts/pll_config.h ${S}/board/altera/cyclone5-socdk/qts
   	install -m 0644 ${WORKDIR}/qts/sdram_config.h ${S}/board/altera/cyclone5-socdk/qts
   }

For more information see u-boot-socfpga/doc/README.socfpga.

Add custom device tree

u-boot

To add an own device tree to u-boot do following steps:

1. Copy the .dts/.dtsi files to meta-custom/recipes-bsp/u-boot/u-boot-socfpga/dts:

   mkdir -p path/to/yocto/poky/meta-custom/recipes-bsp/u-boot/u-boot-socfpga/dts
   cp custom.dts path/to/yocto/poky/meta-custom/recipes-bsp/u-boot/u-boot-socfpga/dts/custom.dts
   cp custom-u-boot.dtsi path/to/yocto/poky/meta-custom/recipes-bsp/u-boot/u-boot-socfpga/dts/custom-u-boot.dtsi

2. Add the .dts/.dtsi files to the u-boot bbappend file:

   cd  path/to/yocto/poky/meta-custom/recipes-bsp/u-boot
   gedit u-boot-socfpga*.bbappend

   Copy the following code to the u-boot bbappend file to copy the files to the correct directory and add them to the correct Makefile:

   SRC_URI += "[...]
   			file://dts/custom.dts \
   			file://dts/custom-u-boot.dtsi \
   			"
   
   do_configure_prepend () {
   	[...]
   	install -m 0644 ${WORKDIR}/dts/custom.dts ${S}/arch/arm/dts
   	install -m 0644 ${WORKDIR}/dts/custom-u-boot.dtsi ${S}/arch/arm/dts
   }

3. Redefine the variable UBOOT_EXTLINUX_FDT_default with the file name of your device tree in the machine configration file of meta-custom:

   sed -i '/^UBOOT_EXTLINUX_FDT_default/s/".*"/"..\/custom.dtb"/g' path/to/yocto/poky/meta-custom/conf/machine/custom.conf

4. Change in menuconfig the device tree to custom.dts:
   1. Run menuconfig as described here: Configure u-boot (Note: If a devtool-fragment.cfg file for u-boot already exists in the meta-custom layer, you should update it manually, otherwise the existing changes there will be deleted)
   2. Go to Boot options → Default fdt file and change the value to 'custom.dtb'
   3. Go to Device Tree Control → Default Device Tree for DT control and change the value to 'custom'

linux kernel

Adding your own device tree to the linux kernel is similar to the steps above:

1. Copy the .dts file to meta-custom/recipes-kernel/linux/linux-altera-lts/dts:

   mkdir -p path/to/yocto/poky/meta-custom/recipes-kernel/linux/linux-altera-lts/dts
   cp custom.dts path/to/yocto/poky/meta-custom/recipes-kernel/linux/linux-altera-lts/dts/custom.dts

2. Add the .dts file to the linux kernel bbappend file:

   cd  path/to/yocto/poky/meta-custom/recipes-kernel/linux
   gedit liunx-altera-lts*.bbappend

   Copy the following code to the linux kernel bbappend file to copy the files to the correct directory during image generation:

   SRC_URI += "[...]
   			file://dts/custom.dts \
   			"
   
   do_configure_prepend () {
   	[...]
   	install -m 0644 ${WORKDIR}/dts/custom.dts ${S}/arch/${ARCH}/boot/dts
   }

3. Redefine the variable KERNEL_DEVICETREE with the file name of your device tree in the machine configration file of meta-custom.

   1. Open the custom.conf file:

       gedit path/to/yocto/poky/meta-custom/conf/machine/custom.conf

   2. Delete the content of the variable KERNEL_DEVICETREE and add your customized device tree:

      KERNEL_DEVICETREE = "custom.dtb"
      

(optional) Add fpga configuration file to meta layer

It is possible to add an fpga configuration file to the meta layer, which is used to configure the fpga from u-boot.

1. First generate an rbf file from the sof file generated by the quartus project:

   1. run the nios ii command shell (Intel Quartus):

      ~/intelFPGA_lite/20.1/nios2eds/nios2_command_shell.sh

   2. run following command to convert the sof file to rbf:

      cd path/to/quartus/project/output_files
      quartus_cpf -c -o bitstream_compression=on custom.sof soc_system.rbf

2. Run following commands to create a recipe in the specified directory:

   mkdir -p path/to/yocto/poky/meta-custom/recipes-bsp/rbf
   cat > path/to/yocto/poky/meta-custom/recipes-bsp/rbf/custom-rbf.bb << EOF
   DESCRIPTION = "Add fpga configuration file to image"
   LICENSE = "MIT"
   LIC_FILES_CHKSUM = "file://\${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" 
   
   PACKAGE_ARCH = "\${MACHINE_ARCH}"
   PV = "1.0\${PR}" 
   
   FILESEXTRAPATHS_prepend := "\${THISDIR}/files:"
   SRC_URI = " file://soc_system.rbf"  
   
   do_install () {
   	install -d \${D}/images/\${MACHINE}
   	install -m 0644 \${WORKDIR}/soc_system.rbf \${D}/images/\${MACHINE}
   	install -d \${DEPLOY_DIR}/images/\${MACHINE}
   	cp \${WORKDIR}/soc_system.rbf \${DEPLOY_DIR}/images/\${MACHINE}
   }
   
   FILES_\${PN} += "/images/\${MACHINE}" 
   
   EOF

3. Create the files folder in meta-custom/recipes-bsp/rbf and copy the rbf file there:

   mkdir -p path/to/yocto/poky/meta-custom/recipes-bsp/rbf/files
   cp path/to/soc_system.rbf path/to/yocto/poky/meta-custom/recipes-bsp/rbf/files/

4. Add with the variable IMAGE_BOOT_FILES the rbf file to the FAT partition of the image in the machine configuration file of meta-custom layer:

   echo -e '\nIMAGE_BOOT_FILES += "soc_system.rbf"' >> path/to/yocto/poky/meta-custom/conf/machine/custom.conf

5. Modify the image recipe to add the createed recipe to your image. This command refers to the provided image core-image-minimal.bb, you can also create your own image recipe and add your created recipes.

   echo -e '\nIMAGE_INSTALL_append = " custom-rbf"' >> path/to/yocto/poky/meta/recipes-core/images/core-image-minimal.bb

6. Add the following commands to CONFIG_BOOTCOMMAND via u-boot menuconfig, so that u-boot will configure the fpga with the rbf file:

   1. Run menuconfig as described here: Configure u-boot (Note: If a devtool-fragment.cfg file for u-boot already exists in the meta-custom layer, you should update it manually, otherwise the existing changes there will be deleted)
   2. Go to Boot options and enable 'Enable a default value for bootcmd'
   3. Change the value of 'bootcmd value' to 'load mmc 0:1 $loadaddr soc_system.rbf; fpga load 0 $loadaddr $filesize; bridge enable; run distro_bootcmd'

References

1. Linux Kernel Development Manual
2. Reference Manual#devtool Quick Reference
3. Board Support Package (BSP) Developers's Guide
4. u-boot-socfpga/doc/README.socfpga
5. Patching the source for a recipe
6. Intel SoC EDS User Guide