4. 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 **[8]**. ==================================================== 4.1 Downloading and installing the BSP ==================================================== The BSP is available on GitHub for CC Linux 4.1 and later versions. You can obtain access to the GitHub BSP repository from the CrossControl customer service. When taking the BSP into use, check that you use a specified release tag. We push continuous updates to the BSP, which means non-tagged BSP versions may not be fully tested. We recommended building the BSP in a Docker container which has the necessary dependencies for the Yocto build system. For setting up the Docker based build environment, check instructions from the Readme file in the root of the BSP repository. A large amount of disk space (400+ GB recommended) 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 **[8]** for information about required dependencies. ==================================================== 4.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 Yocto layers will be fetched from remote repositories upon first build with the repo tool. The following subsections will describe these initial directories. Internet connection is required to build a BSP. We provide a source mirror package for sources used in the build. You will need the source mirror package for the build since CrossControl internal components (ccapi, drivers, etc.) sources are not available on GitHub. Contact the CrossControl customer service for a specific release and platform source mirror package access. Most components in the BSP are released under various open-source licenses. CrossControl's drivers, libraries and middleware are licensed as GPL and LGPLv2.1. 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: .. list-table:: :widths: 30 30 :header-rows: 1 * - Device - Code name * - CCpilot X1200 - x1200 * - CCpilot V700 - v700 * - CCpilot V1000/V1200 - v1x00 * - CCpilot V510/V710 - vx10 * - CCpilot V1090/V1290 - v1x90 * - Yukon development board - yukon Additionally, CrossControl specific components are named “cc”, such as “meta-cc” and “recipes-cc”. --------------------------------------------- 4.2.3 binaries --------------------------------------------- All built images, update files, etc. are placed in the binaries directory which is created upon the first build. --------------------------------------------- 4.2.4 meta-3rd-party --------------------------------------------- .. list-table:: Table 3: Content of the subdirectories in the meta-3rd-party directory in the BSP. :widths: 30 30 :header-rows: 1 * - 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. * - **meta-congatec** - This layer provides support for the Congatec products. * - **meta-summit-radio** - This layer includes drivers, firmware and software for Wi-Fi and Bluetooth connections. --------------------------------------------- 4.2.5 meta-cc/meta-bsp- --------------------------------------------- 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. .. list-table:: Table 4: Content of the subdirectories in the meta-cc directory in the BSP. :widths: 30 30 :header-rows: 1 * - Directory - Content * - **conf** - meta-cc layer configuration files for the 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-cc** - Contains recipes for Crosscontrol specific changes to Crosscontrol packages for particular platforms. * - **recipes-connectivity** - Contains recipes for Bluetooth configuration. * - **recipes-core** - • Image recipes (os image and application image) 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. • Rauc bundle recipes (bootloader, rootfs, appfs, os, system) for all supported devices; these are used to produce CC Linux update image. • Recipe for Rauc software update related configurations and the developement certificates specific to platforms. * - **recipes-graphics** - Platform specific recipes related to graphics (Wayland / Weston / Vulkan-loader). * - **recipes-kernel** - Kernel recipes; board-specific kernel patches, device tree, kernel configuration files. * - **recipes-multimedia** - Platform specific recipes related to multimedia frameworks such as gstreamer, alsa, pulseaudio (applicable only for few platforms). * - **wic** - Wic file particular to the platforms for creating the properly partitioned image. --------------------------------------------- 4.2.6 meta-cc/meta-cc-distro --------------------------------------------- The meta-cc-distro directory contains the Yocto layer with all CrossControl CC Linux specific recipes and the recipes for CrossControl developed applications for CC Linux. The distribution is intended to be a general platform which can be used regardless of the device targeted. --------------------------------------------- 4.2.7 meta-cc/meta-cc-security --------------------------------------------- The meta-cc-security directory contains the Yocto layer with all CrossControl specific recipes related to security such as user login passwords, iptables and secure boot. --------------------------------------------- 4.2.8 meta-cc/meta-cc-yukonbase --------------------------------------------- The meta-cc-yukonbase directory contains the Yocto layer with all the Crosscontrol specific changes to recipes that is common to all the yukon based platforms (V1x00, V1x90, VX10). --------------------------------------------- 4.2.9 meta-clang --------------------------------------------- The meta-clang yocto layer provides clang/llvm as alternative to system C/C++ compiler for OpenEmbedded/Yocto project based distributions. This can cohabit with GNU compiler and can be used for specific recipes or full system compiler. --------------------------------------------- 4.2.10 meta-freescale --------------------------------------------- The meta-freescale yocto layer provides support for the base and for IMX Arm reference boards to use with OpenEmbedded/Yocto projects. --------------------------------------------- 4.2.11 meta-freescale-3rdparty --------------------------------------------- The meta-freescale-3rdparty yocto layer provides support for 3rdparty and partner boards to use with OpenEmbedded/Yocto Freescale's BSP layer. --------------------------------------------- 4.2.12 meta-freescale-distro --------------------------------------------- The meta-freescale-distro yocto layer provides support for additional items to aid in development and exercise board capabilities to use with OpenEmbedded/Yocto Freescale's BSP layer. --------------------------------------------- 4.2.13 meta-imx --------------------------------------------- IMX provides an additional yocto layer called the i.MX BSP Release, named meta-imx, to integrate a new i.MX release with the FSL Yocto Project Community BSP. The meta-imx layer aims to release the updated and new Yocto Project recipes and machine configurations for new releases that are not yet available on the existing meta-freescale and meta-freescale-distro layers in the Yocto Project. The contents of the i.MX BSP Release layer are recipes and machine configurations --------------------------------------------- 4.2.14 meta-intel --------------------------------------------- The meta-intel yocto layer is a OpenEmbedded/Yocto BSP layer for Intel platforms. --------------------------------------------- 4.2.15 meta-openembedded --------------------------------------------- OpenEmbedded-Core is a layer containing the core metadata for current versions of OpenEmbedded. It is distro-less and contains only emulated machine support. The meta-openembedded is a repository with collection of layers for the OpenEmbedded-Core. --------------------------------------------- 4.2.16 meta-qt5 --------------------------------------------- The meta-qt5 is a OpenEmbedded/Yocto compatible meta layer that provides recipes for Qt5 modules. --------------------------------------------- 4.2.17 meta-rauc --------------------------------------------- The meta-rauc yocto layer provides support for integrating the RAUC software update tool into the device. --------------------------------------------- 4.2.18 meta-security --------------------------------------------- The meta-security layer provides security tools, hardening tools for Linux kernels and libraries for implementing security mechanisms. --------------------------------------------- 4.2.19 meta-virtualization --------------------------------------------- The meta-virtualization layer provides support for building Xen, KVM, Libvirt, and associated packages necessary for constructing OpenEmbedded-based virtualized solutions. --------------------------------------------- 4.2.20 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//build. --------------------------------------------- 4.2.21 poky --------------------------------------------- Poky is an integration layer consists of several upstream projects such as BitBake (Yocto build tool), OpenEmbedded-Core (Core modules for OpenEmbedded projects), meta-yocto layer (which has configuration and hardware support components) and the Yocto documetations. These components are all part of the Yocto Project and OpenEmbedded ecosystems. --------------------------------------------- 4.2.22 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. --------------------------------------------- 4.2.23 uuu-package --------------------------------------------- Contains necessary binaries and template files to use with flashing the processor with the NXP provided uuu-tool. ==================================================== 4.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//local.conf **file on your development platform.** .. code-block:: 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/ --------------------------------------------- 4.3.1 Using custom repo manifests --------------------------------------------- By default, repo manifests which are used to fetch external layers for target platform are fetched from *https://github.com/crosscontrol-open-source/ccl-manifest* repository. You can use manifest files inside this repository as a base for configuring your own manifest repository to be used in layer synchronization. To use your own manifest repository, you need to set the following environment variables, inside your build environment, to match your repository location and version. Note that if you have not yet run any **make** commands, you can set the environment variables and make will fetch the correct layers based on the custom manifest, otherwise you need to synchronize manually: .. code-block:: bash # Default values can be examined in *Makefile.rules* and these can be used directly in the *repo init* command $ export REPO_MANIFEST_URL="your-custom-manifest-repo-url" # Can use ssh syntax as well. $ export REPO_MANIFEST_VERSION="main" # can be a branch, tag, commit # You can check the environment variables with: $ printenv # To synchronize the custom manifests, you need to run (target_platform is "imx" for v700, vx10, v1x00, v1x90 and "intel" for x1x00): $ repo init -u $REPO_MANIFEST_URL -m .xml -b $REPO_MANIFEST_VERSION && repo sync .. note:: If your custom layers are in a private repository or your manifest repository is private, you need to use SSH syntax for the URLs and you need to have corresponding SSH keys set up as repo does not allow interactive authentication. E.g. "ssh://git@github.com/USERNAME/your-custom-repo.git" --------------------------------------------- 4.3.2 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.** You might need to edit the *platform//local.conf* file depending on where you extracted the source mirror tarball. 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 OS (bootloader + rootfs(with kernel)) image, the application image and the software update image for all CC Linux devices. For instance, To make the CCpilot V700 release image, type .. code-block:: $ make v700-release-image To make the CCpilot V1000/V1200 OS update bundle, type .. code-block:: $ make v1x00-os-update-bundle To make the CCpilot V1090/V1290 system update bundle, type .. code-block:: $ make v1x90-system-update-bundle **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. **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 binaries are located under *binaries/*. To build your own custom Linux image, either edit the image recipe directly, 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//Makefile* as well. See the CC Linux - Software Guide for instructions on how to program the images to the device. And also check the Readme in cclinux source repository for more build details. --------------------------------------------- 4.3.3 Building applications --------------------------------------------- Provided there exists a recipe for the application, building with the BSP can be done in several ways. The first method is the most straightforward whereas the second and third can be more convenient during development as they are faster and more flexible once setup. --------------------------------------------- 4.3.3.1 Edit base image recipe --------------------------------------------- 1. Include the recipe for the application in the image recipe located in *meta-cc/meta-PLATFORM/recipes-core/images/* : .. code-block:: IMAGE_INSTALL += “applicationname” 2. Make the image as usual: .. code-block:: $ make --------------------------------------------- 4.3.3.2 Build apps with bitbake --------------------------------------------- 1. Make sure you are in the platform/ directory and source the environment script: .. code-block:: $ source oe-env 2. Use bitbake to build your application: .. code-block:: $ bitbake Additional bitbake commands can be invoked as well, for instance, one can use the **–c** flag to recompile the application without re-fetching the source files. --------------------------------------------- 4.3.3.3 Modify recipes with Devtool --------------------------------------------- You may also use **devtool** to edit and modify the program developed. For details, see the Yocto documentation on how to work with devtool. Additionally, if you want to make your own layers and recipes, you should read the Yocto Project Development Tasks Manual **[8]**. .. note:: In order to use the **devtool deploy-target**, the target device needs to have root access and the root partition needs to be mounted with read write. These can be achieved with commands on target device or by flashing it with a modified image with stripped security rules and optional debug features. **Manually change the settings:** 1. Access terminal on target device as **ccs** user which should have sudo priviledge. 2. To enable and allow **root** login and remove root password completely, run the following commands: .. code-block:: bash # Enable root with 'sh' as shell with disabled expiration date. Remove root password $ sudo usermod -U -e -1 -s /bin/sh root && sudo passwd -d root # if you want to still have root password you can omit the last part after && and instead run: $ sudo passwd 3. If you are using **ssh** then you need to change some settings inside */etc/ssh/sshd_config* on target machine: .. code-block:: bash # Set these PermitRootLogin yes PermitEmptyPasswords yes .. note:: For setting static IP address, you should refer to network services respective manual. Default in CC Linux 4 is Network Manager. 4. You can either reboot the device or run the **systemctl** command to reload configurations: .. code-block:: bash # On target machine: $ systemctl daemon-reload # On host machine: $ ssh root@target-ip 5. Finally, to be able to write to root partition, you need to remount it with read write: .. code-block:: bash $ mount -o remount,rw / **Build a modified image for development purposes:** With this method you can add debug features, which can be found in the Yocto development tasks manual **[8]**. 1. Modify *platform/PLATFORM/local.conf* by adding the following: .. code-block:: bash EXTRA_IMAGE_FEATURES += "debug-tweaks allow-empty-password empty-root-password" # Other debug features can be also set in this file. 2. Remove or comment out **usermod** for **root** inside *meta-cc/meta-cc-distro/recipes-core/images/cc-linux-credentials.bb* 3. Remove or comment out the **EXTRA_USERS_PARAMS** in *meta-cc/meta-cc-security/recipes-core/images/cc-linux-credentials.bbappend* 4. Comment out the **sed** command which replaces **root /bin/sh** with **/sbin/nologin** in *meta-cc/meta-cc-security/recipes-core/base-passwd/base-passwd_%.bbappend* 5. Now you should be ready to build the flashing utility and customized image: .. code-block:: bash $ make PLATFORM-uuutool-image 6. Once the build is complete and device is flashed with the modified image, you need to remount the root partition with read write access: .. code-block:: bash mount -o remount,rw / Another alternative approach is to create and use Rauc bundles which is described in the CC Linux Rauc Guide. A brief example of **devtool** usage is shown here. 1. Run **devtool modify **. This will fetch the sources for the recipe and unpack them to a *workspace/sources/* 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 desired changes to the source. 3. Run a build to test the changes - you can run **bitbake ** or build an entire image incorporating the changes assuming a package produced by the recipe is part of an image. It is not necessary to force anything - the build system will detect changes to the source and recompile as required. 4. If desired, test your changes on the target. There is a **devtool deploy-target ** command which will copy the files installed at do_install 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 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 ** 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 ** 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 **. All methods will put the resulting application binaries in *platform//build/tmp/work*. .. note:: When installing extra applications as packages you should take into account that the package database will be snapshotted in /mnt/.rootfs/rw/upperdir/var/lib/opkg/ This won't be updated on upgrades in cclinux 2 and 3, which means "opkg status" will keep showing the old list and complain about dependencies when trying to install other packages. This can be resolved by removing the snapshot. Information about manually installed packages will however be forgotten. --------------------------------------------- 4.3.4 Building without an Internet connection --------------------------------------------- It's also possible to build CC Linux image without network connection. There are three pre-requirements for that: 1. Pre-downloaded source mirror placed on a local directory. 2. SOURCE_MIRROR_URL in *platform//local.conf* points to the source mirror directory 3. All layers already synced. Syncing requires an Internet connection. Sync with the following command. .. code-block:: $ PLATFORM= make -f Makefile.rules repo-init By default the source mirror location is defined as */${HOME}/source-mirrors*. If the contents of the pre-downloaded source mirror package are extracted in that directory they will be automatically picked up. .. note:: If you are building inside a Docker environment, you need to mount the source-mirrors directory to the docker environment if the source-mirrors is outside of cclinux-bsp directory. The change needs to be done to *Docker/docker-compose.yml* file under *volumes:*. It is also possible to generate your own source mirror package by uncommenting the following in the *platform//local.conf* .. code-block:: # Enable generation of mirror archives (.tar.gz) under yocto-downloads # BB_GENERATE_MIRROR_TARBALLS = "1"