Skip to main content
Version: BSP 7.x.y

Reference Documentation for Toradex BSP Layers and Reference Images for Yocto Project

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.

Versions and Source-Code​

See Toradex BSP versions and their information on the table below. There might be several concurrent Toradex BSP versions available at a given point in time, refer to Toradex Embedded Linux Support Strategy. Our Embedded Linux Release Matrix summarizes versions of Yocto/OpenEmbedded, the Linux kernel and U-Boot, and release dates for Toradex Embedded Linux releases.

Toradex VersionStatusDistributionOpenEmbedded/Yocto Project CodenameYocto Project Release
7.0LatestPoky basedscarthgap5.0 LTS
6.0LatestPoky basedkirkstone4.0 LTS
5.7OutdatedPoky baseddunfell3.1 LTS
4.0.0 (deferred*)DeferredPoky basedzeus3.0
3.0OutdatedPoky basedthud2.6
2.8OutdatedÅngström v2017.12rocko2.4
2.7OutdatedÅngström v2016.12morty2.2
2.6 / 2.6.1OutdatedÅngström v2015.12jethro2.0
2.5OutdatedÅngström v2015.06fido1.8
2.4OutdatedÅngström v2014.12dizzy1.7
2.3OutdatedÅngström v2014.06daisy1.6
2.2OutdatedÅngström v2013.12dora1.5
2.1OutdatedÅngström v2013.06dylan1.4

* 4.0.0 is deferred, learn more on https://www.toradex.com/blog/torizon-yocto-project-long-term-support-alignment

Release Notes​

Concise, high-level release notes are published on the News section of toradex.com:

Comprehensive, detailed release notes are maintained on the following pages on the developer website:

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:

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.

info

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 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 NameCorresponding Toradex Module
toradex-smarc-imx95SMARC iMX95
toradex-smarc-imx8mpSMARC iMX8M Plus
aquila-am69Aquila AM69
verdin-imx95Verdin iMX95
verdin-imx8mpVerdin iMX8M Plus
verdin-imx8mmVerdin iMX8M Mini
verdin-am62pVerdin AM62P
verdin-am62Verdin AM62
apalis-imx8Apalis iMX8
apalis-imx6Apalis iMX6
colibri-imx8xColibri iMX8X V1.0C or newer
colibri-imx7-emmcColibri iMX7D 1GB (equipped with eMMC flash)
colibri-imx7Colibri iMX7S 256MB and iMX7D 512MB (equipped with raw NAND flash)
colibri-imx6ull-emmcColibri iMX6ULL 1GB (equipped with eMMC flash)
colibri-imx6ullColibri iMX6ULL 512MB (equipped with raw NAND flash)
colibri-imx6Colibri 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 libc variant 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.

Distrokernel basekernel config
tdx-xwaylandDownstream kernel from SoC vendor (NXP / TI)Default (without the PREEMPT_RT patch)
tdx-xwayland-rtDownstream kernel from SoC vendor (NXP / TI)Fully preemptive (real-time Linux PREEMPT_RT patch)
tdx-xwayland-upstreamMainline kernelDefault (without the PREEMPT_RT patch)
tdx-xwayland-upstream-rtMainline kernelFully 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>.conf defines what is the prefered kernel.
  • rt: Builds the kernel with the CONFIG_PREEMPT_RT_FULL option enabled. Refer to Real-Time Linux for further details.
info

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.

danger

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.

ImageDescription
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-kde provides 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:

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.

Device Tree Overlays​

See below the Device Tree Overlays for different functionality provided by Toradex for each SoM. For more details, check our Device Tree Overlays Overview.

Displays​

info

Default resolution with these overlays: 1920x1080

Native Interface:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_hdmi_overlay.dtbo
Apalis iMX8 QuadMax6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX66.0.0apalis-imx6_hdmi_overlay.dtbo
Colibri iMX66.0.0colibri-imx6_hdmi_overlay.dtbo

Using Toradex DSI to HDMI adapter:

ModuleStarting from versionOverlay
Verdin iMX957.3.0verdin-imx95_dsi-to-hdmi_overlay.dtbo
Verdin iMX8M Plus6.1.0verdin-imx8mp_dsi-to-hdmi_overlay.dtbo
Verdin iMX8M Mini6.1.0verdin-imx8mm_dsi-to-hdmi_overlay.dtbo
Verdin AM626.4.0verdin-am62_dsi-to-hdmi_overlay.dtbo
Verdin AM62P7.3.0verdin-am62p_dsi-to-hdmi_overlay.dtbo
Aquila AM697.1.0aquila-am69_dsi-to-hdmi_overlay.dtbo
SMARC iMX8M Plus7.3.0toradex-smarc-imx8mp_dsi-to-hdmi_overlay.dtbo
SMARC iMX95¹7.3.0toradex-smarc-imx95_dsi-to-hdmi_overlay.dtbo

¹ Requires customized SoM mount. Contact us for further information.

Using Colibri DSI to HDMI adapter:

ModuleStarting from versionOverlay
Colibri iMX8X6.2.0colibri-imx8x_dsihdmi_overlay.dtbo

SPIDEV​

Native Interface:

ModuleStarting from versionInterfaceOverlay
Aquila AM697.1.0SPI 1aquila-am69_spi1_spidev_overlay.dtbo
Aquila AM697.1.0SPI 2aquila-am69_spi2_spidev_overlay.dtbo
SMARC iMX8M Plus7.3.0SPI 0 CS 0toradex-smarc-imx8mp_spi0-cs0_spidev_overlay.dtbo
SMARC iMX8M Plus7.3.0SPI 0 CS 1toradex-smarc-imx8mp_spi0-cs1_spidev_overlay.dtbo
SMARC iMX8M Plus7.3.0SPI 1 CS 0toradex-smarc-imx8mp_spi1-cs0_spidev_overlay.dtbo
SMARC iMX8M Plus7.3.0SPI 1 CS 1toradex-smarc-imx8mp_spi1-cs1_spidev_overlay.dtbo
SMARC iMX957.3.0SPI 0 CS 0toradex-smarc-imx95_spi0-cs0_spidev_overlay.dtbo
SMARC iMX957.3.0SPI 0 CS 1toradex-smarc-imx95_spi0-cs1_spidev_overlay.dtbo
SMARC iMX957.3.0SPI 1 CS 0toradex-smarc-imx95_spi1-cs0_spidev_overlay.dtbo
SMARC iMX957.3.0SPI 1 CS 1toradex-smarc-imx95_spi1-cs1_spidev_overlay.dtbo
Verdin iMX957.3.0SPIverdin-imx95_spidev_overlay.dtbo
Verdin iMX8M Plus6.0.0SPIverdin-imx8mp_spidev_overlay.dtbo
Verdin iMX8M Mini6.0.0SPIverdin-imx8mm_spidev_overlay.dtbo
Verdin AM626.4.0SPIverdin-am62_spidev_overlay.dtbo
Verdin AM62P7.3.0SPIverdin-am62p_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 1apalis-imx6_spi1_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 2apalis-imx6_spi2_spidev_overlay.dtbo
Colibri iMX8X6.1.0SPIcolibri-imx8x_spidev_overlay.dtbo
Colibri iMX6ULL eMMC6.1.0SPIcolibri-imx6ull_spidev_overlay.dtbo

CAN​

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Mini6.1.0CAN 1 [20MHz]verdin-imx8mm_20mhz_can1.dtbo
Verdin iMX8M Mini6.0.0CAN 1 [Disable]verdin-imx8mm_disable_can1.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Apalis iMX8 QuadMax6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo

Camera​

OV5640 CSI Camera​

See the OV5640 CSI Camera in the Developer Wesite.

Native Interface:

ModuleStarting from versionInterfaceOverlay
SMARC iMX957.3.0CSI 0toradex-smarc-imx95_csi0_ov5640_overlay.dtbo
SMARC iMX957.3.0CSI 1toradex-smarc-imx95_csi1_ov5640_overlay.dtbo
SMARC iMX8M Plus7.3.0CSI 0toradex-smarc-imx8mp_csi0_ov5640-27mhz_overlay.dtbo
SMARC iMX8M Plus7.3.0CSI 1toradex-smarc-imx8mp_csi1_ov5640-27mhz_overlay.dtbo
Aquila AM697.1.0CSI 1aquila-am69_csi1_ov5640_overlay.dtbo
Aquila AM697.1.0CSI 2aquila-am69_csi2_ov5640_overlay.dtbo
Verdin iMX957.3.0CSIverdin-imx95_ov5640_overlay.dtbo
Verdin iMX8M Plus6.0.0CSIverdin-imx8mp_ov5640_overlay.dtbo
Verdin iMX8M Mini6.0.0CSIverdin-imx8mm_ov5640_overlay.dtbo
Verdin AM626.4.0CSIverdin-am62_ov5640_overlay.dtbo
Verdin AM62P7.3.0CSIverdin-am62p_ov5640_overlay.dtbo

verdin-am62p_ov5640-27mhz_overlay.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus [Default jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-default-jumpers_overlay.dtbo
Verdin iMX8M Plus [Alternate jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-alt-jumpers_overlay.dtbo
Apalis iMX8 QuadMax6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo

Verdin Mezzanine jumper settings:

Jumper SettingJP3JP4JP5JP6
Default2-32-32-32-3
Alternate2-32-31-21-2

HMP​

Heterogeneous Multicore Processing Overlays:

ModuleStarting from versionOverlay
Verdin AM626.6.0verdin-am62_hmp_overlay.dtbo
Verdin iMX8M Plus6.3.0verdin-imx8mp_hmp_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_hmp_overlay.dtbo
Colibri iMX8X6.4.0colibri-imx8x_hmp_overlay.dtbo

BTL Audio Output on NAU8822​

Verdin Development Board features an analog audio interface based on the NAU8822 24-bit audio codec IC with integrated DSP with specific functions

ModuleStarting from versionOverlay
Verdin iMX957.3.0verdin-imx95_nau8822-btl_overlay.dtbo
Verdin iMX8M Plus6.2.0verdin-imx8mp_nau8822-btl_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_nau8822-btl_overlay.dtbo
Verdin AM626.4.0verdin-am62_nau8822-btl_overlay.dtbo
Verdin AM62P7.3.0verdin-am62p_nau8822-btl_overlay.dtbo

Pre-enabled Device Tree Overlays​

By default, the following overlays are enabled to simplify the use of Toradex carrier boards and modules. Note that these overlays may cause conflicts with other peripherals.

ModuleSupported PeripheralsOverlays
Apalis iMX8HDMI
SPIDEV		apalis-imx8_hdmi_overlay.dtbo
apalis-imx8_spi1_spidev_overlay.dtbo
apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX6HDMI
SPIDEV		apalis-imx6_hdmi_overlay.dtbo
apalis-imx6_spi1_spidev_overlay.dtbo
apalis-imx6_spi2_spidev_overlay.dtbo
Send Feedback!