Silicon Blade

Lesson

Machine Configuration and BSP Basics

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

The Yocto Project Platform Development Lesson 9 of 12

Once you are comfortable with recipes and debugging, the next step is to understand how Yocto becomes specific to a 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?

A BSP layer is the layer that carries hardware support metadata.

BSP stands for Board Support Package.

In practice, a BSP layer often contains:

  • machine configuration files
  • kernel recipes or kernel append files
  • bootloader customisation
  • device tree files or patches
  • firmware packaging
  • hardware-specific configuration fragments

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

Why Separate the BSP Layer

It is usually a mistake to mix hardware-specific metadata with product policy or application logic.

A healthy Yocto project often separates:

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

This makes it easier to answer questions like:

  • is this change tied to hardware or to product policy?
  • could another product reuse the same BSP layer?
  • can the distro be shared across several boards?

Machine Configuration Versus Distribution Configuration

This distinction is one of the most important ideas in a maintainable Yocto project.

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:

  • package policy
  • 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 types of configuration separate 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:

  • kernel selection and version
  • bootloader selection and version
  • device tree handling
  • CPU architecture tuning
  • image formats
  • machine-specific packages and providers

Finding 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:

  • 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, but 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 or memory or making changes to the boot configuration), then using the vendor machine configuration directly is no longer appropriate.

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

At this point, creating your own configuration becomes essential.

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:

The filename becomes the machine name you use in configuration.

So if the file is:

conf/machine/myboard.conf

then the machine name is:

MACHINE = "myboard"

A Simple Machine Configuration Example

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

require conf/machine/nitrogen8mp.conf
MACHINEOVERRIDES:prepend "nitrogen8mp:"

MACHINE_FEATURES = "usbhost usbgadget ethernet"

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

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 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.

You do not need to memorise all of these immediately, but they are part of the normal vocabulary of BSP work.

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.

Configure the Build to Use a Machine

Once the machine configuration exists, you can select it in local.conf:

MACHINE = "myboard"

After that, BitBake will use the metadata associated with that machine when building images, kernels, boot components, and related packages.

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.

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 1 A 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 2 Which of these changes most clearly belongs in BSP or machine metadata rather than distro policy?
Question 3 You need one board-specific fix on top of a vendor BSP. Which approach keeps long-term maintenance under better control?