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

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' path/to/yocto/poky/build/conf/local.conf
   echo -e '\nMACHINE = "cyclone5"' >> path/to/yocto/poky/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"' >> path/to/yocto/poky/build/conf/local.conf
   echo -e 'PREFERRED_VERSION_linux-altera-lts = "5.4%"' >> path/to/yocto/poky/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%"' >> 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. 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"' >> path/to/yocto/poky/build/conf/local.conf
   echo -e 'UBOOT_CONFIG = ""' >> path/to/yocto/poky/build/conf/local.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>"

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

Finish u-boot modification

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' path/to/yocto/poky/build/conf/local.conf
sed -i '/UBOOT_CONFIG = ""/d' path/to/yocto/poky/build/conf/local.conf

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 u-boot 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 required files to custom 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/soc_system_hps_0/ \
   --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://github.com/altera-opensource/u-boot-socfpga/blob/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
   recipetool edit u-boot-socfpga

   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.

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