3. Board Support Package

To provide the possibility to create custom Linux images for CCpilot devices, a board support package (BSP) has been created. The BSP is a Yocto-project build system that produces complete Linux images for the CCpilot devices. It also includes the necessary application and driver code, as well as example or template code that may serve as a basis for further application and driver development.

The open-source Yocto system has built-in package support with many thousands of maintained packages available, while also providing a set of standard tools and build guidelines. The BSP adds necessary drivers and applications required for the CCpilot board images. For more information regarding the Yocto project, please refer to the Yocto Project Development Tasks Manual [9].

3.1 Downloading and installing the BSP

The BSP package comes in the form of a gzipped tar archive which can be acquired from the CrossControl support site. The BSP was created on an x86-64 machine running Ubuntu 18.04.5 LTS and must be unpacked to a Linux host machine/build server. A large amount of disk space (at least several hundred gigabytes) and memory is required for the Yocto system, as the directory structure tends to grow quickly in size. Please refer to the Yocto Project Development Tasks Manual [9] for information about required dependencies.

3.2 BSP structure

This chapter will go through CrossControl specific parts of the BSP structure. For other third-party components (OpenEmbedded, Yocto, etc.), please refer to their respective reference documentation.

Initially, the BSP base directory will only contain CrossControl directories. All other required third-party tools are provided as hash-files which can be downloaded from remote repositories upon first build. The following subsections will describe these initial directories.

Internet connection is required to build a BSP.

While most components in the BSP are released under various open-source licenses, others are of proprietary nature and protected under the CrossControl Software License. Be aware of which license applies and please comply with the license terms.

VX10 is the internal CrossControl code name for the CCpilot VX10 architecture/platform; therefore, the BSP contains references to the VX10 platform such as “PLATFORM_VX10”. The same applies for other CCpilot devices:

Device

Code name

CCpilot X900

xm9

CCpilot X1200

x1200

CCpilot V700

v700

CCpilot V1000/V1200

v1x00

CCpilot V510/V710/V705

vx10

Yukon development board

yukon

Additionally, CrossControl specific components are named “cc”, such as “meta-cc” and “recipes-cc”.

3.2.1 apps

The apps directory contains the source code to CrossControl-developed libraries and applications such as CCAux API library, CCAux daemon, CCSettingsConsole, etc.

3.2.2 drivers

The drivers directory contains the source code to the following CrossControl-developed drivers:

ss

Handles communications between the System Supervisor (SS) and the main processor (MP, i.e. the Linux system) over the MP-SS SPI or I2C bus. This driver is required for the CCAux API to work.

<xx>-io

Is used to set the direction of the internal UART, in order to support either bootloader output to the update board or to the serial port of the SS.

3.2.3 meta-3rd-party

Table 3: Content of the subdirectories in the meta-3rd-party directory in the BSP.

Directory

Content

meta-kontron

This is the base (meta) layer that contains various 3-rd party and Kontron software which is common for all x86 boards produced by Kontron Europe.

meta-kontron-smarc-sxel

This is the base (meta) layer that contains various 3-rd party configurations and software tailored to the SMARC-sXEL CPU module (CCpilot X1200) produced by Kontron Europe.

3.2.4 meta-cc/meta-cc-distro

The meta-cc-distro directory contains the Yocto layer with all CrossControl CC Linux specific recipes. The distribution is intended to be a general platform which can be used regardless of the device targeted.

3.2.5 meta-cc/meta-bsp-<platform>

The BSP ships with the corresponding BSP layer for the target hardware. The BSP layer contains all necessary recipes for providing hardware enablers for the target. The Yukon hardware-based devices also contain the meta-cc/meta-yukonbase layer which has the general parts of the hardware adaptation to reduce overlap between the BSP layers in the hardware family.

See Table 4 for more details of the subdirectories.

Table 4: Content of the subdirectories in the meta-cc directory in the BSP.

Directory

Content

conf

meta-cc layer configuration files for the <xx> machines. The machines are based on more general machines. For instance, the ‘v700’ machine is based on the ‘mx6q’ machine, which in turn is based on the ‘mx8’ machine in the meta-freescale layer.

recipes-bsp

Contains the u-boot specific patches which adapt the default u-boot configuration for the device’s chipset.

recipes-connectivity

Contains recipes for Ethernet configuration.

recipes-core

  • Image recipes (both for the main and rescue system) for all supported devices; these are used to produce the reference CC Linux image. This is a good starting place to add or remove features from the image.

  • Psplash recipe, used to create a bootsplash image during the time in which the Linux system loads

  • Initscript recipes

recipes-kernel

  • Kernel recipes; board-specific kernel patches, device tree, kernel configuration files

    Recipes for the CrossControl developed drivers in the drivers directory

3.2.6 platform

The platform directory contains a directory for each of the CC Linux devices as well as one common directory. These directories contain environment-setup scripts, extra Makefile rules to build individual system components with bitbake, and the configuration files needed for configuring the build system. The file local.conf can be modified to change the default Yocto download directory etc. If you want to add a new layer to the Yocto build, it must be added to the bblayers.conf file.

When building, the working directory will be located in platform/<xx>/ build.

3.2.7 tools

The tools directory contains scripts to be used for device OS update.

See the CC Linux – Software Guide for instructions on how to use them.

3.2.8 uuu-package

Contains necessary binaries and template files to use with flashing the processor with the NXP provided uuu-tool.

3.2.9 binaries

All built images, update files, etc. are placed in the binaries directory which is created upon the first build.

3.3 Using the BSP

The purpose of this chapter is not to give the reader a full description of the Yocto build system and all its possibilities; but rather give useful tips on how to build Linux images and application binaries from within the BSP.

NXP has updated their repository URL as of March 31, 2023. This update has already been implemented in CC Linux 3.3.x and newer versions. However, for previous versions of the BSP, you need to address this issue manually. Please change NXP layers’ recipes URLs to github.com/nxp-imx from source.codeaurora.org/external/imx.

However, performing a manual update requires a significant amount of effort across numerous files. Therefore, we recommend a simple solution: adding the following mirrors to platform/<xx>/local.conf file on your development platform.

MIRRORS:
git://source.codeaurora.org/external/imx/ git://github.com/nxp-imx/
https://source.codeaurora.org/external/imx/ https://github.com/nxp-imx/
http://source.codeaurora.org/external/imx/ http://github.com/nxp-imx/
gitsm://source.codeaurora.org/external/imx/ gitsm://github.com/nxp-imx/

3.3.1 Building Linux images

Out of the box, the BSP produces a CC Linux image containing a reference implementation. The reference implementation is intended to be used as a basis for creating custom images.

The first time building the image can take several hours, depending on your host machine. Subsequent builds will be quicker as Yocto reuses all unchanged components from previous builds.

Depending on your host machine, you might need to edit the platform/<xx>/local.conf file. For instance, the default download directory can be changed; and if you have limited disk space, there is a setting for removing temporary files once builds are completed. However, removing temporary files will slow down your build process.

In the BSP root directory there is a Makefile containing rules to make main and rescue images for all CC Linux devices. For instance, to make the CCpilot V700 release-image, type

$ make v700-release-image

make will automatically source the environment scripts in the platform directory and invoke bitbake to bake the image recipe in the meta-cc/recipes-core/images directory.

The resulting image is located in platform/<xx>.

To build your own custom Linux image, either edit the image recipe right away, or make a new recipe and add a new rule for it to the Makefile. If choosing the latter, don’t forget to add a rule to the platform/<xx>/Makefile as well.

See the CC Linux - Software Guide for instructions on how to program the images to the device.

3.3.2 Building applications

Provided there exists a recipe for the application, building with the BSP can be done in two ways. The first method is the most straightforward whereas the second can be more convenient during development as it is faster and more flexible.

First method:

1. Include the recipe for the application in the image recipe: .. code-block:

IMAGE_INSTALL += “applicationname”

2. Make the image as usual: .. code-block:

$ make <imagerule>
Second method:

1. Make sure you are in the platform/<xx> directory and source the environment script: .. code-block:

$ source oe-env

2. Use bitbake to build your application: .. code-block:

$ bitbake <applicationname>

Third method:

You may also use devtool to edit and modify the program developed. For details, see the Yocto documentation on how to work with devtol.

A brief example is shown here.

  1. Run devtool modify <recipename>. This will fetch the sources for the recipe and unpack them to a workspace/sources/<recipename> directory and initialize it as a git repository if it isn’t already one. If you prefer you can specify your own path, or if you already have your own existing source tree you can specify the path along with the -n option to use that instead of unpacking a new one.

  2. Make the changes you want to make to the source

  3. Run a build to test your changes - you can bitbake <recipename> or build an entire image incorporating the changes assuming a package produced by the recipe is part of an image. There’s no need to force anything - the build system will detect changes to the source and recompile as necessary.

  4. If you wish, test your changes on the target. There’s a “devtool deploy-target” command which will copy the files installed at do_install over to the target machine assuming it has network access, and any dependencies are already present in the image.

  5. Repeat from step 2 as needed until you’re happy with the results.

  6. At this point you will almost certainly want to place your changes in the form of a patch to be applied from the metadata - devtool provides help with this as well. Commit your changes using “git commit” (as many or as few commits as you’d like) and then run either:

    ◦ devtool update-recipe <recipename> to update the original recipe - usually appropriate if it’s your own recipe or you’re submitting the changes back to the upstream layer

    ◦ devtool update-recipe -a <layerpath> <recipename> to put your changes in the form of a bbappend to be applied by a different layer. This is usually the desired method if your changes are customisations rather than bugfixes.

  7. If you’re finished working on the recipe, run devtool reset <recipename>.

All methods will put the resulting application binaries in platform/<xx>/build/tmp/work.

In the second method, additional bitbake commands can be invoked. For instance, one can use the –c flag to recompile the application without re-fetching the source files.