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 11

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.

This is also where many projects become harder to maintain if responsibilities start to blur.

What MACHINE Means

The MACHINE setting selects the hardware target for the build.

For example:

MACHINE = "qemux86-64"

or:

MACHINE = "myboard"

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

Those settings often influence:

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

Where Machine Configuration Lives

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

For example:

meta-my-bsp/
└── conf/
    └── machine/
        └── myboard.conf

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"

What a BSP Layer Is

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

If those responsibilities get mixed together, the project becomes much harder to reuse and maintain.

A Simple Machine Configuration Example

A very small machine configuration might look something like this:

MACHINEOVERRIDES =. "myboard:"

DEFAULTTUNE = "cortexa53"
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:

  • DEFAULTTUNE selects the CPU tuning
  • 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

Machine overrides allow metadata to adapt based on the selected target.

For example:

MACHINEOVERRIDES =. "myboard:"

That means you can write metadata elsewhere such as:

SRC_URI:append:myboard = " file://board-fix.patch"

or:

IMAGE_INSTALL:append:myboard = " myboard-utils"

Overrides are powerful, but they should be used carefully. If too much behaviour is hidden behind them, the project becomes difficult to reason about.

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:

meta-my-bsp/
├── conf/
│   ├── layer.conf
│   └── machine/
│       └── myboard.conf
├── recipes-bsp/
│   ├── u-boot/
│   └── firmware/
├── recipes-kernel/
│   └── linux/
└── recipes-core/
    └── images/

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 truth 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
  • whether SSH should be included in the image
  • which applications belong in a product build
  • company-wide compliance or release policy

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.

A Practical Mental Model

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.

That one question prevents a lot of long-term project pain.

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 becomes much 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?