Page History

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:

   Code Block
   language bash theme Midnight linenumbers true
   cd path/to/yocto/poky git clone -b dunfell https://github.com/kraj/meta-altera.git

   
   

2. Add meta-altera to yocto project with:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   bitbake-layers create-layer path/to/yocto/poky/meta-custom

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   rm -rf path/to/yocto/poky/meta-custom/recipes-example

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

      Code Block
      language bash theme Midnight linenumbers true
      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:

      Code Block
      language bash theme Midnight linenumbers true
      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:

      Code Block
      language bash theme Midnight linenumbers true
      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):

      Code Block
      language bash theme Midnight linenumbers true
      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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   cd path/to/yocto/poky/build/workspace/sources/u-boot-socfpga

   
   

2. Run a build to test your changes:

   Code Block
   language bash theme Midnight linenumbers true
   devtool build u-boot-socfpga

   
   

3. Add the changes made with:

   Code Block
   language bash theme Midnight linenumbers true
   git add .

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   cd path/to/yocto/poky/build/workspace/sources/linux-altera-lts

   
   

2. Run a build to test your changes:

   Code Block
   language bash theme Midnight linenumbers true
   devtool build linux-altera-lts

   
   

3. Add the changes made with:

   Code Block
   language bash theme Midnight linenumbers true
   git add .

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   git commit -m "<message>"

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   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):

   Code Block
   language bash theme Midnight linenumbers true
   ~/intelFPGA_lite/20.1/embedded/embedded_command_shell.sh

   
   

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

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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):

   Code Block
   language js
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language js
   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:

   Code Block
   theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language js
   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:

      Code Block
      theme Midnight linenumbers true
      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:

      Code Block
      language js
      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):

      Code Block
      language bash theme Midnight linenumbers true
      ~/intelFPGA_lite/20.1/nios2eds/nios2_command_shell.sh

      
      

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

      Code Block
      language bash theme Midnight linenumbers true
      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:

   Code Block
   language bash theme Midnight linenumbers true
   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}/testsoc_boardsystem.rbf \${D}/images/\${MACHINE} install -d \${DEPLOY_DIR}/images/\${MACHINE} cp \${WORKDIR}/testsoc_boardsystem.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:

   Code Block
   language bash theme Midnight linenumbers true
   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:

   Code Block
   language bash theme Midnight linenumbers true
   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.

   Code Block
   language bash theme Midnight linenumbers true
   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