Targeted HardwarephyBOARD-Zeta (phyCORE-i.MX7)
Targeted SoftwarePD18.1.x
Date

 



Summary


Customizing a BSP to support a specific application is a common task in designing systems with PHYTEC SoMs. Describing custom hardware, adding packages to your BSP, and adding custom OS services to your BSP are just a few simple examples of customizing a BSP. Yocto enables customization through it's meta-layer scheme. The BSP is described within these layers using recipes. Everything from where Yocto can find the source to how it builds the source and where it is deployed. Customizing a BSP is as simple as adding your own meta-layer. You can find pre-made layers here or you can find instructions on creating your own custom layer below. More specifically, this How To will guide you through adding a package, from an existing recipe, to the standard PHYTEC BSP.

Step-by-step guide

Creating your custom layer


As a reference point, this how-to will begin just before the Quickstart (also called BSP manual) instructs you to execute the 'bitbake <image_name>' command. However, these instructions are relevant for both pre and post build environments. 

Start by creating a development directory within $YOCTO_DIR

mkdir $YOCTO_DIR/development

With your environment variables sourced according to instructions in the respective Quickstart, create your meta layer skeleton and move it to the development directory with the following commands:

cd $YOCTO_DIR/build
yocto-layer create zeta-networkd
mv meta-zeta-networkd ../development/

The 'yocto-layer create' command will create a meta layer with the name specified after this command. It will automatically prepend the "meta-" string.

Congratulations! You have just created a meta-layer. Now is a good time to add your work to a git repository:

cd $YOCTO_DIR/development/meta-zeta-networkd
git init && git add . && git commit -s


Adding networkd to your BSP in your custom meta-layer


Following the directory structure of the base recipe, create a 'systemd_%.bbappend' file within your new meta-layer. The filename indicated will append any version of the systemd recipe included in your BSP. Add the following content to systemd_%.bbappend:

meta-zeta-networkd/recipes-core/systemd/systemd_%.bbappend
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
PACKAGECONFIG_append = " networkd"
RDEPENDS_${PN} += "systemd-machine-units"

This recipe will add networkd to your BSP. We can now use networkd to automatically configure our Ethernet ports upon boot. The next sections will describe creating and adding these configuration files to your BSP.

Creating network configuration files


In the same directory as your systemd_%.bbappend file, create a directory for storing your network configuration files.

cd $YOCTO_DIR/development/meta-zeta-networkd/recipes-core/systemd/
mkdir systemd-machine-units


Within the 'systemd-machine-units' directory, add configuration files that describe the desired network configuration. Some examples can be found below, as well as here.


For dynamic IP

Add the following file '$YOCTO_DIR/development/meta-zeta-networkd/recipes-core/systemd/systemd-machine-units/10-eth0.network':

Configure eth0 with DHCP
[Match] 
Name=eth0

[Network] 
DHCP=yes


For static IP

Add the following file '$YOCTO_DIR/development/meta-zeta-networkd/recipes-core/systemd/systemd-machine-units/10-eth1.network':

Configure eth1 with static IP
[Match]
Name=eth1

[Network]
DHCP=ipv4
Address=192.168.3.11/24


Default network device

Add the following file to create a default network device configuration. '$YOCTO_DIR/development/meta-zeta-networkd/recipes-core/systemd/systemd-machine-units/90-dhcp-default.network'

[Match]
Name=e* w*

[Network]
DHCP=yes


Create a recipe to add your configuration files to the target filesystem


In the same directory as your systemd_%.bbappend file, add the following recipe to populate the BSPs filesystem with your network configuration files:

meta-zeta-networkd/recipes-core/systemd/systemd-machine-units.bb
SUMMARY = "Machine specific systemd units"

LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

PACKAGE_ARCH = "${MACHINE_ARCH}"

PR = "r23"
inherit systemd

NATIVE_SYSTEMD_SUPPORT = "1"
ALLOW_EMPTY_${PN} = "1"

# Don't generate empty -dbg package
PACKAGES = "${PN}"

SRC_URI = " \
    file://10-eth0.network \
    file://10-eth1.network \
    file://90-dhcp-default.network \
"

do_install() {
    install -d ${D}${systemd_unitdir}/network/
    for file in $(find ${WORKDIR} -maxdepth 1 -type f -name *.network); do
        install -m 0644 "$file" ${D}${systemd_unitdir}/network/
    done
    install -d ${D}${systemd_system_unitdir}/
    for file in $(find ${WORKDIR} -maxdepth 1 -type f -name *.service); do
        install -m 0644 "$file" ${D}${systemd_system_unitdir}/
    done
}

# Ship directory "/lib/systemd/system" explicitly in case it is empty. Avoids:
#     QA Issue: systemd-machine-units: Files/directories were installed but not shipped
FILES_${PN}_append = " \
    ${systemd_system_unitdir} \
    ${systemd_unitdir}/network/ \
"

Adding your meta layer to bblayers.conf


Now that you have completed development of your custom meta layer, you will need to add it to the list of layers that Yocto will build. To do this, we must modify the bblayers.conf file. Start by copying the existing configuration files, bblayers.conf.sample and local.conf.sample, from the standard BSP into your meta layer's 'conf' directory:

mkdir $YOCTO_DIR/development/meta-zeta-networkd/conf
cp $YOCTO_DIR/sources/meta-phytec/meta-phytec-fsl/conf/bblayers.conf.sample $YOCTO_DIR/development/meta-zeta-networkd/conf/bblayers.conf.sample
cp $YOCTO_DIR/sources/meta-phytec/meta-phytec-fsl/conf/local.conf.sample $YOCTO_DIR/development/meta-zeta-networkd/conf/local.conf.sample

These configuration files specify which layers will be built (bblayers.conf.sample) and define your local build environment (local.conf.sample).

Add your layer to to bblayers.conf.sample. Following the format of the existing layers, add your meta layer's name to the list of layers. Below is an example of a bblayers.conf.sample file with the meta-zeta-networkd layer added:

$YOCTO_DIR/development/meta-zeta-networkd/conf/bblayers.conf.sample
# LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
LCONF_VERSION = "7"

BBPATH = "${TOPDIR}"
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"
BBFILES ?= ""

BBLAYERS = " \
        ${BSPDIR}/sources/poky/meta \
        ${BSPDIR}/sources/poky/meta-poky \
        \
        ${BSPDIR}/sources/meta-openembedded/meta-oe \
        ${BSPDIR}/sources/meta-openembedded/meta-multimedia \
        \
        ${BSPDIR}/sources/meta-freescale \
        ${BSPDIR}/sources/meta-freescale-3rdparty \
        ${BSPDIR}/sources/meta-freescale-distro \
        \
        ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-bsp \
        ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-sdk \
        ${BSPDIR}/sources/meta-browser \
        ${BSPDIR}/sources/meta-openembedded/meta-gnome \
        ${BSPDIR}/sources/meta-openembedded/meta-networking \
        ${BSPDIR}/sources/meta-openembedded/meta-python \
        ${BSPDIR}/sources/meta-openembedded/meta-filesystems \
        ${BSPDIR}/sources/meta-qt5 \
        \
        ${BSPDIR}/sources/meta-phytec \
        ${BSPDIR}/sources/meta-phytec/meta-phytec-fsl \
        ${BSPDIR}/sources/meta-zeta_networkd \
  "

You can also add local environment variables to the local.conf.sample file. Now is a good time to check in your code changes and push your files to a remote git repo.

Update the build manifest


The final step before we can build our custom BSP is updating the build manifest to include our custom meta layer git repo. This allows our build to be automated and repeatable. Start by copying the standard BSP's manifest into a new, git managed, directory. In this example, I will use the '/opt/PHYTEC_BSPs/manifests' directory.

cp $YOCTO_DIR/.repo/manifest.xml /opt/PHYTEC_BSPs/manifests/manifest_phycore_imx7_networkd.xml
vim /opt/PHYTEC_BSPs/manifests/manifest_phycore_imx7_networkd.xml

Modify the manifest file to include a 'remote' element, to describe your remote repo location, and a 'project' element to describe the local destination for your layer. See the '$YOCTO_DIR/.repo/repo/docs/manifest-format.txt' file for details on the contents of the manifest file.

<remote fetch="<<<Your custom meta-layer git repo URL goes here>>>" name="custom_meta_layer"/>


...


<project remote="custom_meta_layer" revision="<<<Branch name that contains your manifest>>>" name="meta-zeta-networkd" path="sources/meta-zeta-networkd" />

Now is a good time to check in your code changes and push your files to a remote git repo.

Build your custom BSP


You are now ready to build your custom BSP!

Let's start with a new directory for our custom BSP.

mkdir /opt/PHYTEC_BSPs/imx7_custom_bsp
cd /opt/PHYTEC_BSPs/imx7_custom_bsp
mkdir yocto_imx7
mkdir yocto_dl
cd yocto_imx7
export YOCTO_DIR=`pwd`

Initialize and sync remote repositories, locally.

cd $YOCTO_DIR
repo init -u <<<Your custom manifest git repo URL goes here>>> -b <<<Your custom manifest git repo branch name goes here>>> -m manifest_phycore_imx7_networkd.xml
repo sync

Specify your build configuration to set up the build environment.

cd $YOCTO_DIR
TEMPLATECONF=$YOCTO_DIR/sources/meta-zeta-networkd/conf source sources/poky/oe-init-build-env build

Be sure to configure your local.conf with any further additions (as described in the Quickstart Guide).

Now start the build.

cd $YOCTO_DIR/build
MACHINE=<Yocto Machine> bitbake fsl-image-validation-imx


Conclusion

This How to guide has demonstrated one possible process for adding a package to a standard PHYTEC BSP by using an existing bitbake recipe. Specifically, we have added the networkd package from the systemd recipe and created configuration files that describe how networkd will configure network interfaces.