BSP Layers and Reference Images Architecture

Introduction

Toradex BSP Layers provide the hardware-specific foundation for building embedded Linux systems for Toradex System on Modules (SoMs). They integrate Toradex hardware support with OpenEmbedded Core, community layers, and the layers maintained by the SoC vendors. Toradex Reference Images add a reference distribution and image recipes to this foundation.

The BSP layers are production-quality building blocks. The Reference Images are intended for evaluating the BSP and as starting points for developing a custom image; they are not production-ready operating systems without further customization.

This article describes the layer and repository boundaries, the build configuration model, and the path from source metadata to deployable artifacts. For release lifecycle information, refer to the Embedded Linux Support Strategy. For the exact component versions supported on each SoM, refer to the Embedded Linux Release Matrix.

Architecture Overview

The following view separates the sources that provide build metadata from the configuration choices that select a product and from the artifacts produced by BitBake:

Build setup configuration
  sources and revisions + selected configuration fragments
                              |
                              v
OpenEmbedded and Yocto layers
  OpenEmbedded Core and community layers
  SoC-vendor layers
  Toradex BSP layers
  Toradex distribution and Reference Image layers
                              |
                              v
Build configuration
  MACHINE + TDX_BSP_VARIANT + DISTRO + image recipe
                              |
                              v
BitBake artifacts
  bootloader + firmware + kernel + device trees + root filesystem
                              |
                              v
Toradex Easy Installer image or other deployment artifact

Each configuration input has one primary responsibility:

Input	Responsibility	Examples
MACHINE	Selects the target SoM and its hardware defaults	Processor, memory, storage, and default BSP variant
TDX_BSP_VARIANT	Selects a coordinated hardware support stack	Kernel, device tree, and SoC-vendor BSP mode
DISTRO	Selects userspace and distribution policy	Init system, graphics policy, packaging, and distribution features
Image recipe	Selects the packages installed in the root filesystem	Reference Minimal Image or Reference Multimedia Image
Configuration fragments	Record optional, selectable build configuration	BSP variants and setup options

Together, these inputs define the hardware support, userspace policy, and root filesystem contents of a build.

Source and Layer Organization

BSP Repository

Toradex maintains its BSP layers in the meta-toradex-bsp Git repository. The repository contains separate OpenEmbedded layers for common Toradex metadata and SoC-specific BSP metadata.

The repository organization reflects the scope of the metadata:

• Common metadata applies across Toradex SoM families.
• SoC-specific metadata integrates the corresponding vendor BSP and platform components.
• Each build includes the layers required by its target platform.

Adjacent Toradex Layers

The complete Reference Image offering also includes the following Toradex and upstream layers:

Layer or repository	Responsibility
meta-toradex-bsp	Common and SoC-specific machine support, kernel and bootloader integration, device trees, firmware integration, and BSP variants
meta-toradex-distro	Toradex Reference Image distribution policy, including the tdx-xwayland distribution
meta-toradex-demos	Reference Image recipes and related packages; it also provides the Toradex registry used to initialize Reference Image builds
SoC-vendor layers	Vendor BSP metadata and the vendor-owned configuration interfaces used by the Toradex BSP
OpenEmbedded Core and community layers	Build system, core recipes, classes, and common software metadata

Keeping the distribution and images outside the BSP repository also lets other operating systems, including Torizon OS, use the Toradex BSP layers without inheriting the Reference Image userspace policy.

BSP Variants

A BSP variant is a coordinated selection of hardware-facing providers and policies for a specific MACHINE. A variant can select:

• the Linux kernel provider and configuration;
• the device tree provider;
• upstream or SoC-vendor-specific BSP behavior;
• a real-time kernel configuration, when such a variant is available.

The variant sets these related choices together. You do not need to configure several provider variables independently and risk combining components that Toradex has not integrated as a stack.

The machine configuration defines a default variant and the variants available for selection. Variant availability and support are machine-specific.

info

The kernel version is a property of the selected BSP variant, not only of the BSP major version. Use the Embedded Linux Release Matrix to identify the integrated kernel, U-Boot, firmware, and Yocto Project versions for a supported configuration.

Configuration Fragments

Toradex exposes variants as standard OpenEmbedded configuration fragments. A variant fragment sets TDX_BSP_VARIANT; the selected value then drives the compatible provider and vendor-layer configuration.

Conceptually, a Reference Image build has independent configuration axes:

MACHINE = "<machine>"
DISTRO = "<distribution>"
TDX_BSP_VARIANT = "<machine-compatible-variant>"

The BSP variant and distribution are independent configuration axes. The standard OpenEmbedded local.conf file provides a customization point for project-specific settings.

Upstream and Downstream Variants

An upstream variant follows components from the upstream Linux and U-Boot projects as closely as the platform permits. A downstream variant uses an SoC-vendor BSP when platform enablement or features depend on vendor-maintained components.

Both types use the same configuration model. The variant configures the vendor layer through the BSP-selection interfaces owned by that layer.

Use the default variant unless your product requires a capability or maintenance model offered by another supported variant. Upstream and downstream are not general quality levels: their feature coverage and support scope depend on the SoM and release.

Real-Time Variants

Where Toradex provides real-time support, it is represented by a BSP variant. Kernel scheduling behavior is therefore independent from the userspace policy selected by DISTRO and the image recipe.

Distribution and Image Responsibilities

The tdx-xwayland distribution defines Toradex Reference Image userspace policy. It does not identify whether the build uses an upstream, downstream, or real-time BSP implementation.

An image recipe defines the root filesystem contents on top of that policy. Toradex provides two BSP Reference Images:

• Reference Minimal Image provides a small command-line system suitable as a bottom-up starting point.
• Reference Multimedia Image includes a larger evaluation environment with graphical and multimedia capabilities.

The image recipe does not replace the BSP variant. For example, choosing the Reference Multimedia Image adds userspace packages but does not independently select a kernel or device tree provider.

Build Initialization

Toradex uses bitbake-setup to initialize Reference Image build environments. The tool is part of BitBake and consumes configuration templates that describe sources, revisions, layers, and selectable fragments.

Toradex provides its Reference Image configuration registry under meta-toradex-demos/default-registry. When you initialize a setup, the workflow:

1. Reads a Toradex configuration template from the registry.
2. Presents the choices defined by that template, including the target machine and available BSP variants.
3. Fetches the configured layers at their specified revisions.
4. Creates the BitBake build directory and configuration instance.
5. Records the selected configuration in the configuration instance.

The resulting setup separates three kinds of state:

Directory	Contents
layers/	Source repositories managed by bitbake-setup
build/	The active BitBake build tree, configuration, and build output
config/	The configuration template instance, selections, and source revision information

The generated sources-fixed-revisions.json file captures the exact source revisions of an initialized setup. Archive this information with build artifacts when you need to reproduce the source checkout. A setup that deliberately uses a moving source revision remains non-reproducible until that revision is fixed.

Customization Boundary

Use a customer layer to keep product-specific metadata separate from the Toradex and vendor layers. Typical ownership is:

Requirement	Recommended location
Carrier board or custom hardware description	Customer machine configuration, device trees, and overlays
Kernel configuration or an additional driver	Customer recipes and .bbappend files
Product services and applications	Customer recipes and image metadata
Package selection	Customer image recipe or image append
Organization-wide userspace policy	Customer distribution layer
Local developer or build-host settings	local.conf or site configuration

Application package choices belong in image metadata, and kernel implementation choices belong in a BSP variant. These boundaries keep product policy independent from hardware enablement.

Toradex Easy Installer Images

A Toradex Easy Installer-compatible image is a structured deployment package rather than a different Linux distribution. It is the default format for Toradex reference images.

The architecture provides several controls useful for production programming:

• Target compatibility: supported_product_ids associates an image with compatible SoMs and helps prevent programming it onto an unsupported module.
• Declarative storage layout: blockdevs and mtddevs describe eMMC and raw NAND operations, including partitions, filesystems, compressed payloads, and raw writes.
• Unattended delivery: the same package can be discovered on SD card or USB storage, or served over HTTP. The autoinstall property enables no-touch installation.
• Per-device hooks: preparation, completion, and error scripts receive the product ID, hardware revision, and serial number. A production flow can use this context for product-specific programming, validation, logging, or traceability.
• Installer compatibility: config_format defines the installer version required by an image. A newer Toradex Easy Installer image can be supplied with the product image so that the installer is updated before programming when required.

These responsibilities make Toradex Easy Installer the recommended deployment layer for repeatable programming of supported Toradex SoMs.

For implementation details, refer to Toradex Easy Installer Overview, Production Programming for Linux, and Using Wic Files.

Related Documentation

• BSP Layers and Reference Images Overview
• Build a Reference Image with Yocto Project
• Quick Reference
• BSP Layers Issue Tracker