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
- kas Configuration — the surrounding project and build configuration
- Build Your Own BSP Layer — a walkthrough that ends at this page
- Configure meta-tolomeo for Your Machine — check a machine configuration for completeness
- Enable FIT Image Signing — sign the kernel FIT image
- Enable NXP Authenticated Boot — sign the i.MX boot chain
- Generate a HAB4 PKI Tree — create the i.MX8M signing keys
- Generate an AHAB PKI Tree — create the i.MX9 signing keys
- Secure Boot — classes, includes and variables
- Secure Boot Chain — how the chain of trust fits together