Integrate an Evaluation Board into your Yocto Ecosystem

Integrate an Evaluation Board into your Yocto Ecosystem

· 1,942 words · 10 minutes reading time English Yocto

This blog post describes how to add a new (evaluation) board to your Yocto ecosystem. It is done as a step by step example. The evaluation board is the phyBOARD-Polis i.MX8M Mini 1-4 GB RAM: (with a phyCORE®-i.MX 8M Mini SOM). The Yocto system to integrate to is our ams reference system, where we experiment with and have various showcases for some general problems.

Motivation

All the evaluation boards on the market come a long with a vendor specific Yocto integration these days. This integration contains a working and maintained BSP specification (machine config where kernel, device tree and boot loader is derived from).

The various vendors provide similar but different ways to initialize their Yocto build system:

  • Different bsp and middleware layers are pulled
  • Different init scripts need to be applied such that finally the bitbake command can be invoked.
  • Different distro definition might cause different tmp* pathes

What you want to have is a homogene approach to

  • Initialize a build
  • Run the build
  • Consume the build output

It should be independent upon the the type of board, SOM or vendor, while reusing the BSP integration effort the vendor already did. More importantly, it should allow for easy reuse of vendor maintained SOM-BSP software and configuration.

Also you might not favor the middleware (e.g. for software update, ) or you might not be bothered with the sample application the vendor provides.

Having the SOM evaluation board (via a machine specification) as part of your Yocto ecosystem, it is straight forward to derive a new machine specification from the SOM evaluation board by mainly:

  • Adapting the device tree
  • Reconfiguring the kernel/kernel modules
  • Modifying the boot process

This is almost risk-less engineering, since the evaluation board vendor already removed almost all engineering risks and did almost all the necessary work for you.

Also, it allows you to evaluate upstream BSP changes provided by the SOM vendor on the evaluation board first, before upgrading your own board BSP. This requires to intregrate the evaluation board BSP into your Yocto environment.

Step by Step

1. Explore and verify the Vendor's Yocto Integration

You need to:

  • Understand what the vendor did and how
  • Verify, that you can actually configure, build, deploy and run an image suggested by the vendor
  • Inspect the repo manifest e.g. default.xml to determine the mandatory layers references for your derived manifest
  • Use the bsp the generated local.conf and bblayers.conf as a blueprint for your integration

PhyTec uses a pyhLinux script to setup the build environment. phyLinux to be downloaded here

  • The script downloads phytecs repo tool variant (v2.28), It does not use the upstream (v2.40)
  • phyLinux init
    • Selects the manifest file (different files for different yocto versions and cpu chips)
    • Syncs the recipe repositories
    • Creates build/conf/local.conf and build/conf/bblayers.conf
      • Build folder cannot be different
      • Not derived from upstream TEMPLATE folder
    • Example Phyboard Polis PL 1532.1 with phyCore-i.MX 8M Mini
      • Select imx8mm as board (IMX8 Mini based som)
      • Select PD23.0 hat maps to Yocto Kirkstone (aka 4.0 LTS)

2. Create a BSP Integration Manifest

The initial manifest is the same copied from the the one selected in step 1. it is located in yocto ams manifests repository and is located in the repo-manifests/experimental folder with the original manifest-name in the PhyTec universe

The original file named phytec-BSP-Yocto-NXP-i.MX8MM-PD23.1.0.xml and it is extended by ams layers, such that we are ready to integrate

  <remote name="ams" fetch="ssh://git@github.com/almedso"/>
  <project name="yocto-ams" revision="master" path="sources/ams" remote="ams">
	  <copyfile dest="README.md" src="README.md"/>
	  <linkfile dest="init-build-env" src="scripts/ams-init-build-env"/>
	  <linkfile dest="phyimx8-not-integrated-init-build-env" src="scripts/ams-init-build-env"/>
  </project>

Note

The ams layer repo also contains the adaptable build init script that we link into our main folder. This link will not take effect, since we have not adapted the script yet.

Now it is time to pull the sources using the repo too as follow.

repo init -u git@github.com:almedso/yocto-ams-manifests.git \
          -m repo-manifests/experimental/phytec-BSP-Yocto-NXP-i.MX8MM-PD23.1.0.xml

Add the following case at the end of the script scripts/ams-init-build-env:

                phyimx8-not-integrated-init-build-env)
                        main phyimx8-not-integrated meta-ams-bsp
                        ;;

It will pull the phyimx8-not-integrated template from the meta-ams-bsp. We directly derive the template from the build/conf/local.conf and build/conf/bblayers.conf as created in step 1. via phyLinux init script

$ tree meta-ams-bsp/conf/templates/
meta-ams-bsp/conf/templates/
└── phyimx8-not-integrated
    ├── bblayers.conf.sample
    ├── conf-notes.txt
    └── local.conf.sample

4 . Run the build

Initialize the build environment by sourcing our modified script

. phyimx8-not-integrated-init-build-env

The newly established local.conf.sample and bblayers.conf.sample are prepared for the build.

It results to an output like:


Use template phyimx8-not-integrated from layer meta-ams-bsp


Source init script from poky
You had no conf/local.conf file. This configuration file has therefore been
created for you from /home/volker/yocto/ams-kirkstone/sources/ams/meta-ams-bsp/conf/templates/phyimx8-not-integrated/local.conf.sample
You may wish to edit it to, for example, select a different MACHINE (target
hardware). See conf/local.conf for more information as common configuration
options are commented.

You had no conf/bblayers.conf file. This configuration file has therefore been
created for you from /home/volker/yocto/ams-kirkstone/sources/ams/meta-ams-bsp/conf/templates/phyimx8-not-integrated/bblayers.conf.sample
To add additional metadata layers into your configuration please add entries
to conf/bblayers.conf.

The Yocto Project has extensive documentation about OE including a reference
manual which can be found at:
    https://docs.yoctoproject.org

For more information about OpenEmbedded see the website:
    https://www.openembedded.org/


██████╗ ██╗  ██╗██╗   ██╗████████╗███████╗ ██████╗
██╔══██╗██║  ██║╚██╗ ██╔╝╚══██╔══╝██╔════╝██╔════╝
██████╔╝███████║ ╚████╔╝    ██║   █████╗  ██║
██╔═══╝ ██╔══██║  ╚██╔╝     ██║   ██╔══╝  ██║
██║     ██║  ██║   ██║      ██║   ███████╗╚██████╗
╚═╝     ╚═╝  ╚═╝   ╚═╝      ╚═╝   ╚══════╝ ╚═════╝


Welcome to the PHYTEC BSP-Yocto buildsystem.

Before building for the first time, you should take a look in the main
configuration file 'conf/local.conf'. There you can tweak the build system
settings and license configuration. For example you may have to accept the
Freescale/NXP GPU and VPU license for an i.MX6 board.

Tested build target for this build configuration is:

   $ bitbake phytec-headless-image


Update site.conf - from sample in project root

Now you can start the build process

MACHINE=phyboard-polis-imx8mm-4 bitbake phytec-headless-image

After a successful build, the created image is located at ./deploy/images/phyboard-polis-imx8mm-4.

This time we decide to boot from SD-Card. Insert the SD-Card into your development host. (Here we assume that it will be /dev/sdb.)

cd deploy/images/phyboard-polis-imx8mm-4
sudo  bmaptool copy --bmap phytec-headless-image-phyboard-polis-imx8mm-4.wic.bmap phytec-headless-image-phyboard-polis-imx8mm-4.wic  /dev/sdb

Insert the SD-Card into the board. Make sure the boot switches are configured for SD-Card boot. Connect the console and watch the boot process:


 ____   _   _ __   __ _____  _____   ____
|  _ \ | | | |\ \ / /|_   _|| ____| / ___|
| |_) || |_| | \ V /   | |  |  _|  | |
|  __/ |  _  |  | |    | |  | |___ | |___
|_|    |_| |_|  |_|    |_|  |_____| \____|

    _     __  __  ____   _      ___  ____   _   _ __   __
   / \   |  \/  ||  _ \ | |    |_ _||  _ \ | | | |\ \ / /
  / _ \  | |\/| || |_) || |     | | | |_) || |_| | \ V /
 / ___ \ | |  | ||  __/ | |___  | | |  __/ |  _  |  | |
/_/   \_\|_|  |_||_|    |_____||___||_|    |_| |_|  |_|


ampliPHY Vendor (Phytec Vendor Distribution) BSP-Yocto-NXP-i.MX8MM-PD23.1.0 phyboard-polis-imx8mm-4 ttymxc2

phyboard-polis-imx8mm-4 login:
CTRL-A Z for help | 115200 8N1 | NOR | Minicom 2.7.1 | VT102 | Offline | ttyUSB0

At this point we have integrated the build initialization and build process. Also, we have checked that the Phytec image, that we just have built, actually boots.

5. Integrate the Polis BSP into AMS Configuration

We achieved two things so far:

  • We are able to reproduce the build, that the vendor suggested for the evaluation board. This is needed, later on if upstream changes coming along and they do not work we can review if the upstream change work on the eval board. We keep our "ground truth" working and can identify if the potential error is caused by upstream changes --> we ask for vendor support. Or, if it is caused by us --> we have to fix our own adaptation.
  • We have a blueprint to derive integrated manifest and template. The next sections reveal the details.

5.1. Extend our Integration Manifest by Polis BSP Layers

Create a new experimental manifest repo-manifests/experimental/ams-polis.xml

  • It is derived from repo-manifests/experimental/phytec-BSP-Yocto-NXP-i.MX8MM-PD23.1.0.xml.
  • It contains another sourceable init script link
  <remote name="ams" fetch="ssh://git@github.com/almedso"/>
  <project name="yocto-ams" revision="master" path="sources/ams" remote="ams">
	  <copyfile dest="README.md" src="README.md"/>
    ...
	  <linkfile dest="phyimx8-init-build-env" src="scripts/ams-init-build-env"/>
    ...
  </project>
  • It does not contain not needed recipe repositories like meta-rauc, meta-qt6, meta-virtualization, meta-qt6-phytec, meta-ampliphy, meta-nxp-demo-experience

5.2. Extend our Integration Template

Next, we integrate the Phytec (BSP) layers into the AMS configuration by adapting bblayer.conf and local.conf to build an AMS distro based image.

  • We create a new template called phyimx8.
  • Populate the init script link and init template at the end of the script scripts/ams-init-build-env.
    Add the following case:
                phyimx8-init-build-env)
                        main phyimx8 meta-ams-bsp
                        ;;

It will pull the phyimx8 template from the meta-ams-bsp.

$ tree meta-ams-bsp/conf/templates/
meta-ams-bsp/conf/templates/
└── phyimx8
    ├── bblayers.conf.sample
    ├── conf-notes.txt
    └── local.conf.sample
  • local.conf.sample - is the same file that we use for all our BSP's. It sets the ams-bsp distro as new default.
  • bblayers.conf.sample - is derived from previous conf/bblayers.conf puls meta-ams-bsp layer.
  • conf-notes.txt - provides arbitrary information that is presented after sourcing the phyimx8-init-build-env script.

5.3. Build an Test the fully AMS integrated Image on the Polis Board

Now you can start the build process

# get the configuration and recipes into place
repo init -u  git@github.com:almedso/yocto-ams-manifests.git -m repo-manifests/experimental/polis-kirkstone.xml
repo sync
# initialize for the phytec polis board
source phyimx8-init-build-env
Use template phyimx8 from layer meta-ams-bsp


Source init script from poky
       _                    _
  __ _| |_ __ ___   ___  __| |___  ___
 / _` | | '_ ` _ \ / _ \/ _` / __|/ _ \
| (_| | | | | | | |  __/ (_| \__ \ (_) |
 \__,_|_|_| |_| |_|\___|\__,_|___/\___/


Welcome to almedso BSP-Yocto Linux buildsystem.

Default distro: ams-bsp
Default machine: phyboard-polis-imx8mm-4

Run

   bitbake bsp-image-dev

To build a bsp development image.

The build environment is initialzed. The directory is changed to phyimx8-build The build can be started by

$ bitbake bsp-image-dev

5.4. Flash the build to target

The build process stores the created image at ./tmp-glibc/deploy/images/phyboard-polis-imx8mm-4.

We decide to boot from SD-Card again: Insert the SD-Card into your development host. (Here we assume that it will be /dev/sdb.)

cd tmp-glibc/deploy/images/phyboard-polis-imx8mm-4
sudo  bmaptool copy --bmap bsp-image-dev-phyboard-polis-imx8mm-4.wic.bmap bsp-image-dev-phyboard-polis-imx8mm-4.wic  /dev/sdb

Insert the SD-Card into the board. Make sure the boot switches are configured for SD-Card boot. Connect the console and watch the boot process that ends like:

[  OK  ] Reached target Login Prompts.
[  OK  ] Reached target Multi-User System.
         Starting Record Runlevel Change in UTMP...
[  OK  ] Finished Record Runlevel Change in UTMP.

  ___  ___  ___ _____   _     _
 / _ \ |  \/  |/  ___| | |   (_)
/ /_\ \| .  . |\ `--.  | |    _ _ __  _   ___  __
|  _  || |\/| | `--. \ | |   | | '_ \| | | \ \/ /
| | | || |  | |/\__/ / | |___| | | | | |_| |>  <
\_| |_/\_|  |_/\____/  \_____/_|_| |_|\__,_/_/\_\

AMS Distribution 2020-Q3 phyboard-polis-imx8mm-4 ttymxc2

phyboard-polis-imx8mm-4 login:

Conclusion

Yocto is all about automated collaboration of business actors in the embedded Linux industry. SOM vendors provide and maintain BSP's for their SOM's and evaluation boards.

This blog post shows how to integrate an yocto bsp layer of a SOM vendor into your Yocto system. We use our own AMS Yocto system and use a phytec Polis evaluation board containing a IMX 8 Mini SOM. as an example.