Quick Reference
Introduction
This article presents information relevant for building images with Toradex BSP Layers and Reference Images, such as Yocto branches, manifests, Yocto build parameters and others. This article is not meant to be followed linearly, and instead supplements other pages.
If you wish to build a reference image with Yocto for your SoM, refer to: Build a Reference Image with Yocto Project/OpenEmbedded.
Manifests
A repo manifest is a configuration .xml file used with the repo tool to manage multiple Git repositories as a single project.
To build an image with Yocto, several layers of metadata are used to define the build instructions and configurations, and each of these layers is maintained in a git directory. Our Yocto Layers are avalable at git.toradex.com, and are used together with a number of other layers to build images for our SoMs.
The collection of Toradex and third-party layers used on a specific BSP release are provided in our official manifests, available at toradex-manifest. The manifest is necessary when setting up the repositories for building with Yocto.
There are two main groups of manifests for building Toradex images, which are located at the toradex-manifest:
tdxref: Manifests for building Reference Images with our BSPtorizon: Manifest for building Torizon and Torizon Reference Images
The repository also contains manifests in the tezi directory, for building Toradex Easy Installer.
The bsp and base directories are used by the other directories as dependencies.
Since Torizon 7, the torizoncore manifest directory changed its name to torizon.
Manifest File
Each manifest directory contains three manifests you can choose from:
default.xml: Used to build the monthly release (default) or the quarterly release (by choosing the corrresponding release tag).integration.xml: Used to build the nightly release.next.xml: Used for our internal tests. Never build your images using this manifest.
It is recommended to use default.xml. The other two manifest files are used by Toradex to monitor future changes and may not be stable.
Image Components
The OS images built with Yocto are consist of several components. A non-exhaustive list of these components is shown below:
- Kernel: Manages hardware resources, provides low-level services, and offers an interface for applications to interact with the hardware. It is the core part of the operating system (OS).
- Bootloader: Runs at system startup to initialize hardware and load the kernel into memory. Toradex images use U-Boot by default.
- Board Support Package (BSP): A collection of software (drivers, configurations, patches) that allows the kernel to run on the device. Refer to our BSP Layers and Reference Images for Yocto Project documentation for further details
- Init System: The first user-space process started by the kernel; it initializes and manages system services, daemons, and the overall startup/shutdown process.
- Device Trees: Data structures that describe the hardware components of a system (CPUs, memory, peripherals) to the kernel. Refer to our Device Trees Documentation for further details
- Modules: Loadable pieces of code (e.g., device drivers, filesystems) that can be added to or removed from a running kernel without recompiling or rebooting.
For information on the components' versions on each of our releases, check our Embedded Linux Release Matrix.
Build Variables
Openembedded / Yocto gets the distribution policy from a configuration file which is set by the DISTRO variable in local.conf.
Machine
The MACHINE variable specifies the target device for the Yocto image. Set this variable to the module you are planning to build for.
Toradex's BSP layers provide the following machines:
| Machine Name | Corresponding Toradex Module |
|---|---|
aquila-am69 | Aquila AM69/TDA4 |
aquila-imx95 | Aquila iMX95 |
verdin-imx95 | Verdin iMX95 |
verdin-imx8mp | Verdin iMX8M Plus |
verdin-imx8mm | Verdin iMX8M Mini |
verdin-am62p | Verdin AM62P |
verdin-am62 | Verdin AM62 |
lino-imx93 | Lino iMX93 |
toradex-osm-imx93 | OSM iMX93 |
toradex-smarc-imx95 | SMARC iMX95 |
toradex-smarc-imx8mp | SMARC iMX8M Plus |
apalis-imx8 | Apalis iMX8 |
apalis-imx6 | Apalis iMX6 |
colibri-imx8x | Colibri iMX8X V1.0C or newer |
colibri-imx7-emmc | Colibri iMX7D 1 GB (equipped with eMMC flash) |
colibri-imx6ull-emmc | Colibri iMX6ULL 1 GB (equipped with eMMC flash) |
colibri-imx7 | Colibri iMX7S 256 MB and iMX7D 512 MB (equipped with raw NAND flash) |
colibri-imx6ull | Colibri iMX6ULL 512 MB (equipped with raw NAND flash) |
colibri-imx6 | Colibri iMX6 |
Distro
The DISTRO variable specifies the target distribution for the image, and are defined at meta-toradex-distro/conf/distro/. The distribution defines what variants of the Linux Kernel, tools, libraries and additional software will be used on the final image.
Some (non-exhaustive) examples of parameters defined by the distribution are:
- The configuration set for the kernel
- What
libcvariant is used - What is the init system (default:
systemd) - If the instruction set is ARM or THUMB
- What package manager is used
- What features of individual packages are available for usage
Toradex provides several distribution policy (DISTRO) files based on Poky, summarized in the table below. All distributions set the policy for the graphics stack (Weston/Wayland + XWayland), but you must select an image with the graphics libraries included in order to get graphical output.
| Distro | kernel base | kernel config |
|---|---|---|
| tdx-xwayland | Downstream kernel from SoC vendor (NXP / TI) | Default (without the PREEMPT_RT patch) |
| tdx-xwayland-rt | Downstream kernel from SoC vendor (NXP / TI) | Fully preemptive (real-time Linux PREEMPT_RT patch) |
| tdx-xwayland-upstream | Mainline kernel | Default (without the PREEMPT_RT patch) |
| tdx-xwayland-upstream-rt | Mainline kernel | Fully preemptive (real-time Linux PREEMPT_RT patch) |
The distro name suffixes determine which additional configurations are applied by each distro
upstream: Builds the mainline kernel and userspace drivers, instead of the downstream kernel maintained by Toradex. Each<machine>.confdefines what is the prefered kernel.rt: Builds the kernel with theCONFIG_PREEMPT_RT_FULLoption enabled. Refer to Real-Time Linux for further details.
For all iMX8 based machines we use the downstream kernel. The mainline kernel does not (yet) contain the features needed for production use. For the iMX8M based modules, there is experimental compatibility with upstream distros.
Make sure to set the correct distro for iMX6/7 modules. Starting from BSP 6, only upstream distros are supported.
Image
The image is the recipe which lists all packages which have to be built and installed into the final root file system.
You can use the reference images as a base for your project, but these images are not production-ready, as they lack security features and standard embedded linux production configurations. The available image recipes are located in meta-toradex-demos/recipes-images/images/.
Toradex provides two reference image variants, built on top of the BSP distributions. Below, we list the image variants, their descriptions, and some notable features. To learn about all the features, follow the links, which point to the relevant Yocto recipes. These images are primarily for BSP evaluation, and we do not recommend using them as-is.
Additionally, we provide a Torizon OS Yocto Reference Minimal Image for OS evaluation. To build images for production, we recommend building on top of a Torizon OS Reference Image. For information on building Torizon images with Yocto, refer to Torizon OS Yocto Reference Minimal Image and Build Torizon OS from Source With Yocto Project/OpenEmbedded.
| Image | Description |
|---|---|
| Reference Minimal Image tdx-reference-minimal-image | Minimal image without a graphical interface that just boots - Network manager: connman- Init system: systemd- Base command-line packages: packagegroup-base-tdx-cli. Included in packagegroup-tdx-cli.bb |
| Reference Multimedia Image tdx-reference-multimedia-image | Image for BSP verification with Qt and multimedia features - All that is included in the Reference Minimal Image - Graphics stack: Weston / Wayland + XWayland - Graphical User Interface framework: Qt - Camera and Video framework: V4L2 and Gstreamer - All command-line packages included in packagegroup-tdx-cli.bb - All graphical packages included in packagegroup-tdx-graphical.bb - All Qt5 packages included in packagegroup-tdx-qt5.bb |
Yocto Recipes and Meta Layers
Yocto recipes and meta-layers provide the configuration meta-data that defines how an image will be built with Yocto:
- Recipes are sets of meta-information that tell OpenEmbedded how to download, compile and deploy software packages for a target device.
- Layers are directory trees which organize recipes that provide similar functionality together. As an example,
meta-kdeprovides recipes to build packages for KDE workspace and applications.
The sections below show the list of layers for building an image with our BSP and for Torizon OS.
Torizon OS Layers
We provide our Torizon OS manifest and layers on https://github.com/toradex:
- meta-toradex-torizon: Provides metadata to build Torizon OS.
Toradex BSP Layers
We provide our Toradex BSP manifest and layers on https://git.toradex.com.
- meta-toradex-bsp-common: BSP layer common to all Toradex computer on modules. Enables interaction between the kernel and Toradex modules.
- meta-toradex-demos: Provides recipes used by our reference images, and the recipes of the images themselves.
- meta-toradex-distro: Provides distribution configuration and recipes to build our reference images.
- meta-toradex-nxp: Provides support for Toradex modules that use NXP SoCs.
- meta-toradex-ti: Provides support for Toradex modules that use Texas Instruments (TI) SoCs.