Machine Configuration¶

The machine configuration is the one part of a ToloMEO integration that meta-tolomeo cannot supply: it describes your hardware. This page documents the contract meta-tolomeo expects a machine to satisfy, and the machine includes it provides to satisfy most of it.

Hardware bring-up itself — kernel, device tree, bootloader port — is outside this contract. What follows is only what ToloMEO's distribution and application layers require in order to run on a machine once it boots.

For the surrounding project and build configuration, see kas Configuration. For a walkthrough that ends at this page, see Build Your Own BSP Layer.

The contract¶

A ToloMEO machine configuration has four parts:

Parts 1 and 4 are yours. Parts 2 and 3 are provided by meta-tolomeo-bsp.

Machine configurations belong in your BSP layer, <project>-bsp/conf/machine/. Where you have several variants of one board — a development flavour, a production flavour, a provisioning flavour — put everything common in conf/machine/include/<project>-<soc>.inc and keep each .conf thin.

Worked example¶

meta-tolomeo-qemu/conf/machine/tolomeo-qemux86-64.conf is the reference implementation of all four parts. It targets QEMU rather than real hardware, but the structure is exactly what a board machine configuration looks like:

#@TYPE: Machine
#@NAME: Tolomeo QEMU x86-64 machine
#@DESCRIPTION: Tolomeo QEMU x86-64 machine based on qemux86-64

# Set machine overrides to inherit qemux86-64 behavior
MACHINEOVERRIDES =. "qemux86-64:"

# (1) the base machine
require conf/machine/qemux86-64.conf

# (2) storage profile and (3) secure boot, both from meta-tolomeo-bsp
require conf/machine/include/tolomeo-mmc-storage.inc
require conf/machine/include/u-boot-secure-boot.inc

MACHINE_FEATURES:remove = "alsa screen"

# (4) board-specific overrides
OVERLAYFS_ETC_DEVICE = "/dev/vdb5"

TLM_APP_DIR = "/app"
TLM_APP_FSTYPE = "ext4"
TLM_APP_DEVICE = "/dev/disk/by-partlabel/A"

KMACHINE = "qemux86-64"

Everything QEMU-specific in that file — QB_MEM, QB_OPT_APPEND, virtfs — occupies the same slot that your UBOOT_CONFIG, storage device paths and WIC layout will occupy. MACHINEOVERRIDES =. "<base>:" is what makes the base machine's :append and :remove overrides apply to your machine too; set it whenever you derive from an existing machine.

Storage profiles¶

Two profiles are provided. Require exactly one.

Both define the same variables; only the filesystem types and device defaults differ:

The two ?= assignments are the ones a machine is expected to override. The defaults describe a conventional layout, not your board's.

The profiles set mount points and filesystem types only. They do not create partitions — your WIC (.wks) layout or flash layout must produce partitions matching the devices you configure.

Optional application partition¶

TLM_APP_DIR, TLM_APP_FSTYPE and TLM_APP_DEVICE configure a separate application partition. They are consumed by the app-mount recipe, which currently lives in meta-tolomeo-qemu and is not installed by any package group, so these variables are required only if you install app-mount yourself. app-mount also calls bbfatal on an empty TLM_APP_DEVICE or TLM_APP_FSTYPE.

Secure boot¶

conf/machine/include/u-boot-secure-boot.inc enables U-Boot FIT image generation and signing:

Requiring this include is safe regardless of whether you enable secure boot: with secure-boot absent from DISTRO_FEATURES, UBOOT_SIGN_ENABLE evaluates to 0 and nothing is signed. Enable the feature in your distribution when your key material and board fuses are ready.

Because local.conf is parsed before the machine configuration, the values the kas fragment writes take precedence over the ?= defaults above — the include's defaults only apply if no kas fragment set them.

Layer placement¶

Machine configurations must live in a layer whose conf/layer.conf declares its dependencies. A BSP layer deriving from a vendor BSP depends on it:

LAYERDEPENDS_meta-tolomeo-acme-bsp = "core meta-desk-mx-bsp"
LAYERSERIES_COMPAT_meta-tolomeo-acme-bsp = "scarthgap"

Use core alone when your base machine comes from poky. Give your layers a BBFILE_PRIORITY above meta-tolomeo's so that your .bbappend files and recipe overrides win.

To verify a machine configuration is complete, follow the checklist in Configure meta-tolomeo for Your Machine.