Create and configure custom meta layer

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 operating system 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
cd ..

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:

   bitbake-layers add-layer ./meta-altera

Create custom meta 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 ./meta-custom

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

   rm -rf ./meta-custom/recipes-example

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

   sed -i '/LAYERDEPENDS_meta-custom/s/core/meta-altera/g' meta-custom/conf/layer.conf 

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

   bitbake-layers add-layer ./meta-custom

Add required parameters to local.conf

1. First the variable "MACHINE" must be redefined in the local.conf file. Several machines are defined in the meta-altera layer (see meta-altera/conf/machine for more information). In this example, the machine 'cyclone5' is used.
   Remove the default value and add 'cyclone5':

   sed -i '/^MACHINE/s/MACHINE/#MACHINE/g' build/conf/local.conf
   echo -e '\nMACHINE = "cyclone5"' >> build/conf/local.conf

2. For the linux kernel in the meta-altera layer it's required to define a the preferred provider and version in local.conf (see meta-altera/recipes-kernel/linux for other linux kernel versions):

   echo -e '\nPREFERRED_PROVIDER_virtual/kernel = "linux-altera-lts"' >> build/conf/local.conf
   echo -e 'PREFERRED_VERSION_linux-altera-lts = "5.4%"' >> build/conf/local.conf
   

3. Set the preferred u-boot version for meta-altera in local.conf (see meta-altera/recipes-bsp/u-boot for other u-boot versions):

   echo -e '\nPREFERRED_VERSION_u-boot-socfpga = "v2021.04%"' >> build/conf/local.conf

Configure custom meta layer with devtool

Create workspace

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

devtool create-workspace

Configure u-boot

To modify the default configuration and create patches of u-boot do following steps:

1. It is not possible to call menuconfig if UBOOT_CONFIG is defined. But UBOOT_CONFIG is needed to assign a defconfig file to UBOOT_MACHINE. UBOOT_MACHINE must therefore be defined manually. The variable UBOOT_CONFIG is predefined in the machine configuration file for cyclone5 with the value 'cyclone5-socdk' (see meta-altera/conf/machine/cyclone5.conf). The associated defconfig file is therefore socfpga_cylcone5_defconfig (see meta-altera/recipes-bsp/u-boot/u-boot-socfpga-common.inc). Accordingly these variables must be defined in local.conf:

   echo -e '\nUBOOT_MACHINE = "socfpga_cyclone5_defconfig"' >> build/conf/local.conf
   echo -e 'UBOOT_CONFIG = ""' >> build/conf/local.conf

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

   devtool modify u-boot-socfpga -O

3. Make changes to u-boot configuration

   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.
4. Make changes to the u-boot source files

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

      cd 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>"

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

      cd <path_to_yocto>/poky

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

   devtool update-recipe u-boot-socfpga -a ./meta-custom -O

6. Remove the UBOOT_CONFIG and UBOOT_MACHINE variables from local.conf if you use the default defconfig file for the MACHINE 'cyclone5':

   sed -i '/UBOOT_MACHINE = "socfpga_cyclone5_defconfig"/d' build/conf/local.conf
   sed -i '/UBOOT_CONFIG = ""/d' build/conf/local.conf

Configure linux kernel

To modify the default configuration and create patches of linux kernel do following steps:

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

   devtool modify linux-altera-lts -O

2. Launch menuconfig with following command and make your changes, exit and save your configuration:

   devtool menuconfig linux-altera-lts

3. Make changes to the linux-altera-lts configuration

   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.
4. Make changes to u-boot source files

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

      cd 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 a - d, otherwise navigate back to the poky directory:

      cd <path_to_yocto>/poky

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

   devtool update-recipe linux-altera-lts -a ./meta-custom -O

Remove workspace

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

bitbake-layers remove-layer workspace
rm -rf build/workspace

Add custom files to custom meta layer

References

1. Linux Kernel Development Manual
2. Reference Manual#devtool Quick Reference
3. u-boot-socfpga/doc/README.socfpga
4. Patching_the_source_for_a_recipe