Silicon Blade

Lesson

Machine Configuration and BSP Basics

How machine settings, BSP layers, and hardware-specific metadata shape a Yocto build

The Yocto ProjectPlatform DevelopmentLesson 10 of 16

Once you are comfortable with creating and modifying recipes, the next step is to understand how to customise Yocto for a specific piece of hardware.

This is where machine configuration and BSP layers come in. They describe the target board or SoC family and provide the metadata that lets the build system produce something that can actually boot and run on that hardware.

What is a BSP Layer?

In essence, the BSP (Board Support Package) is all the information and recipes needed to get a board to boot all the may through to user space.

In practice, a BSP layer often contains:

  • machine configuration files
  • Trusted Firmware (e.g. TF-A)
  • Trusted Execution Environment (OP-TEE)
  • bootloader and customisation
  • kernel recipes or kernel append files
  • device tree files or patches
  • firmware packaging
  • hardware-specific configuration fragments

This is the layer where board-specific support usually belongs.

Why Separate the BSP Layer

A Yocto project often separates:

  • BSP metadata in meta-my-bsp
  • distro or policy metadata in meta-my-distro
  • application recipes in meta-my-software

Having a separate hardware layer gives a level of abstraction.

  • Could another product reuse the same board?
    • Then we can just bring in an existing BSP layer
  • Can the distro be shared across several boards?
    • Then we can just swap out the BSP layer for another board

Machine Configuration Versus Distribution Configuration

Machine configuration usually describes:

  • the target CPU architecture and tuning
  • which kernel or bootloader should be used
  • which device tree or firmware is required
  • supported image or boot artifact formats
  • hardware-specific providers and low-level options

Distribution configuration usually describes:

  • init system choice
  • enabled platform features
  • default runtime behaviour
  • compliance and product-level defaults

For example:

  • choosing systemd is usually a distro decision
  • choosing a board-specific kernel defconfig is usually a machine or BSP decision

Keeping these in separate layers makes the project easier to maintain.

What MACHINE Means

The MACHINE setting selects the hardware target for the build.

For example:

MACHINE = "qemux86-64"

or:

MACHINE = "raspberrypi5"

This tells Yocto which machine configuration file to use and, through that, which hardware-specific settings should shape the build.

Those settings should set things like:

  • CPU architecture tuning
  • which kernel and version
  • which bootloader to use and what version
  • device trees
  • image formats
  • machine-specific variables and metadata

Finding Existing Machine Configurations

If you are using a common development board, there is a high chance that there will already be a configuration for the machine.

In the same way that it is possible to search for recipes, it is possible to search for existing machines.

  1. Go to https://layers.openembedded.org/layerindex/branch/master/machines/
  2. Select your Yocto Project release branch
  3. Search for your your machine

You can then add that layer to your project and set the MACHINE= to that machine name.

Adding your Own Machine

Working with a Supported Development Board

Even when working with an existing development board, it is good practice to define your own machine configuration rather than relying directly on one provided by a vendor BSP as these tend to be generic rather than optimised for your specific project.

By creating your own machine configuration (even if it simply includes or mirrors the original), you:

  • Call the machine the same as internal project name for that board
  • Maintain control over your build configuration
  • Avoid modifying vendor layers directly (which breaks maintainability)
  • Protect yourself from upstream changes when the BSP is updated
  • Create a stable foundation for future customisation

While your machine config may start as a thin wrapper around the vendor machine, it gives you a clean place to make project-specific adjustments later.

Using a Modified Development Board

If your hardware differs from the standard board (typically adding peripherals, memory or just making changes to the boot configuration), then using the vendor machine configuration directly is no longer an option.

In this case, your own machine configuration allows you to:

  • Define a custom device tree
  • Adjust kernel and bootloader settings
  • Enable/disable hardware features
  • Reflect the true hardware capabilities of your platform

Create the Machine Configuration

In most cases, bringing in the vendor layer and then either copying the standard board configuration into your own layer (renaming it to match your project board name) or ‘requiring’ it is a good place to start. From there, you can start modify it to meet your requirements.

Machine configuration files normally live in a BSP layer under conf/machine.

For example:

Configure the Build to Use a Machine

Once the machine configuration exists, you can select it in local.conf. After that, BitBake will use the metadata associated with that machine when building images, kernels, boot components, and related packages.

The filename (without the .conf) becomes the machine name you use in configuration.

So if the file is:

conf/machine/myboard.conf

then the machine name that you would use in the configuration is:

MACHINE = "myboard"

If the machine name is wrong or the relevant BSP layer is missing from bblayers.conf, the build will not be able to resolve the machine metadata.

A Simple Machine Configuration Example

A very basic `conf/machine/myboard.conf may look like:

require conf/machine/am335x-evm.conf
MACHINEOVERRIDES:prepend "am335x-evm"
MACHINE_FEATURES = "usbhost usbgadget ethernet"

KERNEL_DEVICETREE = "vendor/myboard.dtb"
UBOOT_MACHINE = "myboard_defconfig"

This example is for a bespoke board based on the am335x, such the the BeagleBone Black.

This is only an example, but it shows the kind of information machine metadata usually provides.

In this example:

  • MACHINE_FEATURES describes hardware capabilities
  • KERNEL_DEVICETREE points to the board device tree
  • UBOOT_MACHINE selects the bootloader configuration

MACHINE_FEATURES

MACHINE_FEATURES is used to describe capabilities of the hardware.

For example:

MACHINE_FEATURES = "screen keyboard pci wifi bluetooth"

Recipes and package groups may use these features to decide whether support should be enabled or whether certain packages should be included.

These are hardware capabilities, not product preferences.

For example:

  • wifi in MACHINE_FEATURES means the hardware supports Wi-Fi
  • enabling a particular Wi-Fi management stack may still be a distro or image decision

MACHINEOVERRIDES

The MACHINEOVERRIDES allows your board to claim to be an additional machine type. This is actually quite useful as several recipes including U-Boot and the Kernel use the machine name to set the configuration.

By setting the MACHINEOVERRIDES to a pre-defined board allows yur board to make use of that board configuration.

Some common variables you will encounter in BSP work include:

MACHINE

Selects the active machine configuration.

MACHINE_FEATURES

Describes hardware capabilities of the target.

MACHINEOVERRIDES

Adds machine-specific override names for conditional metadata.

DEFAULTTUNE

Selects the CPU tuning used for the target.

KERNEL_DEVICETREE

Identifies the device tree blob or blobs to build and deploy.

UBOOT_MACHINE

Selects a U-Boot configuration where U-Boot is used.

Providers and Board-Specific Selections

Machine metadata is also often used to select the correct provider for low-level components.

For example, a project may need to choose:

  • which kernel recipe should provide the virtual kernel
  • which bootloader should be used
  • which firmware package is correct for a board family

That may look like:

PREFERRED_PROVIDER_virtual/kernel = "linux-myvendor"

This kind of selection often belongs in BSP or machine-related metadata because it is tied to the hardware platform.

Typical BSP Layer Structure

A BSP layer often grows into something like this:

The exact structure varies, but the main idea is that board support lives in its own layer and stays separate from the rest of the project.

Working with Vendor BSP Layers

In real projects, you will often start from a vendor-provided BSP layer rather than building everything yourself.

That usually means:

  • adding the vendor BSP layer to bblayers.conf
  • selecting one of the machine files the vendor already provides
  • appending or extending the vendor metadata from your own layer

This is usually the safest approach because it lets you build on tested hardware support instead of forking it immediately.

What Belongs in the BSP and What Does Not

A useful rule of thumb is:

put hardware configuration in the BSP, and put product policy somewhere else.

Good BSP examples

  • kernel provider selection for a board
  • bootloader configuration
  • device tree handling
  • hardware firmware packaging
  • machine tuning and machine features

Better kept outside the BSP

  • whether the product should use systemd (distro)
  • whether SSH should be included in the image (image)
  • which applications belong in a product build (image)
  • company-wide compliance or release policy (distro)

Keeping this boundary clear makes it much easier to reuse one BSP with several products or distributions.

What Lives Where?

When you are deciding where a piece of metadata should live, ask:

  1. Is this true because of the hardware?
  2. Or is it true because of the product or distro policy?

If it is true because of the board, SoC, boot chain, or hardware capability, it probably belongs in the BSP or machine metadata.

If it is true because of how you want the platform to behave as a product, it probably belongs in the distro, image, or application layer.

Summary

Machine configuration is how Yocto becomes specific to a hardware target.

BSP layers carry the metadata that describes the board, kernel, bootloader, device tree, tuning, and other hardware-related details.

If you keep machine metadata separate from distro policy and application logic, your project will be easier to scale, reuse, and maintain.

Check your understanding

Quick quiz: machine and BSP basics

Check the key hardware-specific boundaries from this lesson.

Question 1A build must target a new board variant with its own boot chain and device tree. Which setting is the entry point for selecting that hardware metadata?
Question 2Which of these changes most clearly belongs in BSP or machine metadata rather than distro policy?
Question 3You need one board-specific fix on top of a vendor BSP. Which approach keeps long-term maintenance under better control?