Skip to content

Machine Configuration

A ToloMEO machine configuration combines a base machine, a storage profile, the secure-boot include and board overrides.

The Contract

meta-tolomeo cannot supply the machine configuration: it describes your hardware. Hardware bring-up itself (kernel, device tree, bootloader port) is outside the contract. A ToloMEO machine configuration has four parts:

# Part How
1 The base machine require your SoC vendor's or poky's machine configuration
2 A storage profile require conf/machine/include/tolomeo-{mmc,mtd}-storage.inc
3 Secure boot require conf/machine/include/u-boot-secure-boot.inc
4 Board-specific overrides Set the device paths the storage profile leaves as ?=, plus your own

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 flavor, a production flavor, a provisioning flavor — 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"

# … QEMU-specific settings: virtfs, QB_MEM, QB_OPT_APPEND

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

Profile For MACHINE_FEATURES OVERLAYFS_ETC_FSTYPE Default OVERLAYFS_ETC_DEVICE Default TLM_CERTS_DEVICE
tolomeo-mmc-storage.inc eMMC / SD / block devices mmc ext4 /dev/mmcblk0p5 /dev/disk/by-partlabel/certs
tolomeo-mtd-storage.inc NAND flash via UBI mtd ubifs /dev/ubi0_4 /dev/ubiblock0_5

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

Variable Set by profile Meaning
TLM_DATA_DIR /data Persistent writable mount point, base for the /etc overlay
OVERLAYFS_ETC_MOUNT_POINT /data Where the overlay upper layer lives
OVERLAYFS_ETC_FSTYPE per profile Filesystem of the data partition
OVERLAYFS_ETC_DEVICE ?= per profile Override this with your partition or volume
TLM_CERTS_DIR /certs Read-only device certificate mount point
TLM_CERTS_FSTYPE squashfs Filesystem of the certificate partition
TLM_CERTS_DEVICE = in mmc, ?= in mtd; value per profile Override this with your partition or volume

The ?= assignments are the ones a machine is expected to override; the mmc profile hard-assigns TLM_CERTS_DEVICE, so override it after the require. The defaults describe a conventional layout, not your board's.

Warning

TLM_CERTS_DEVICE and TLM_CERTS_FSTYPE are not optional. The certs-mount recipe is pulled in by packagegroup-tlm-cloud through the connhex-edge-agent recipe, and it calls bbfatal if either variable is empty. Requiring a storage profile satisfies this; setting the variables by hand also works.

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

Variable Value Notes
UBOOT_SIGN_ENABLE 1 when tlm-secure-boot is in DISTRO_FEATURES, else 0 Signing follows the distribution, not the machine
UBOOT_SIGN_KEYDIR ?= "keys" Normally already set to ${BSPDIR}/keys by the meta-tolomeo-bsp kas fragment
UBOOT_SIGN_KEYNAME ?= "dev" Normally already set to fitImage-sign by the same fragment
UBOOT_FIT_GENERATE_KEYS ??= "0" Keys are provisioned explicitly, never auto-generated
UBOOT_MKIMAGE_DTCOPTS -I dts -O dtb -p 2000 Reserves space in the device tree for the signature

Requiring this include is safe regardless of whether you enable secure boot: with tlm-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. The meta-tolomeo layers use BBFILE_PRIORITY 9 or 10; a layer whose .bbappend files and recipe overrides must win needs a priority above 10.

See also