Build System
meta-pantavisor is the Yocto/OpenEmbedded layer that builds Pantavisor-based BSP images for embedded Linux products. It provides recipes, BitBake classes, and KAS configurations for producing initramfs images and container pvrexport bundles. For the build workflow itself, see Get started.
Key Directories
meta-pantavisor/
├── classes/ # BitBake classes
├── conf/ # Layer and distro configuration
│ └── multiconfig/ # Per-multiconfig TMPDIR settings
├── dynamic-layers/ # Conditional recipes for other layers
├── kas/ # KAS configuration fragments
│ ├── build-configs/ # One-file release build configs
│ ├── machines/ # Per-machine configurations
│ └── platforms/ # Platform-specific layer includes
├── recipes-containers/
│ └── pv-examples/ # Example containers for xconnect testing
├── recipes-pv/ # Core pantavisor recipes
│ ├── images/ # Appengine and BSP image recipes
│ ├── pantavisor/ # Pantavisor runtime
│ └── pvr/ # PVR tool
├── recipes-devtools/ # Development tools (json-sh, fdisk)
└── wic/ # WIC disk image layout files
Key Recipes
| Recipe | Description |
|---|---|
recipes-pv/pantavisor/pantavisor_git.bb | Core Pantavisor runtime (C, cmake-based); SRCREV forwarded from pantavisor.inc |
recipes-pv/images/pantavisor-initramfs.bb | Initramfs image |
recipes-pv/images/pantavisor-bsp.bb | BSP image (generates pvrexport bundles) |
recipes-pv/images/pantavisor-starter.bb | Flashable starter disk image (.wic) |
recipes-pv/pvr/pvr_*.bb | PVR CLI tool (Go-based) |
recipes-pv/lxc6-pv/lxc6-pv_git.bb | Pantavisor-specific LXC 6 fork (default, lxc-stable) |
recipes-pv/lxc7-pv/lxc7-pv_git.bb | Pantavisor-specific LXC 7 fork (lxc-next) |
recipes-pv/lxc-pv/lxc-pv_git.bb | Pantavisor-specific LXC 3 fork (lxc-deprecated) |
BitBake Classes
| Class | Description |
|---|---|
classes/pvbase.bbclass | Defines PANTAVISOR_FEATURES variable and defaults |
classes/pvrexport.bbclass | PVR export functionality for images |
classes/container-pvrexport.bbclass | Container pvrexport packaging |
classes/pvr-ca.bbclass | Certificate authority handling |
classes/pvroot-image.bbclass | Root container image support |
KAS Configuration Hierarchy
KAS is the primary build system. Configuration is composed by layering YAML fragments:
| File | Description |
|---|---|
kas/bsp-base.yaml | Base configuration for BSP builds; defines repos and core settings |
kas/bsp-multi.yaml | Multiconfig builds (separate configs for initramfs and containers) |
kas/scarthgap.yaml / kas/kirkstone.yaml | Yocto release-specific patches and branches |
kas/machines/*.yaml | Per-machine configurations |
kas/platforms/*.yaml | Platform-specific layer includes (sunxi, raspberrypi, etc.) |
kas/with-workspace.yaml | Overlay for local pantavisor source development |
Build configs
kas/build-configs/ holds the build configs you pass to kas build directly.
The release/ ones pin a machine and are self-contained. The build-base-*
ones are minimal bases (image target + a couple of features) that expect a
machine fragment prepended, as in .github/machines.json. kas menu does not
use these files — it writes its own .config.yaml from Kconfig, including the
pantavisor-starter + pv-flash-bundle (± recovery multiconfig) target set for
factory-flash machines via the "Also build pv-flash-bundle" prompt.
| Config | Machine | Target |
|---|---|---|
build-base-starter.yaml | (from kas menu) | pantavisor-starter |
build-base-remix.yaml | (from kas menu) | pantavisor-remix |
build-appengine-distro.yaml | (from kas menu) | pantavisor-appengine-distro |
release/96boards-orangepi-i96-scarthgap.yaml | orangepi-i96 | pantavisor-starter |
release/colibri-imx6ull-scarthgap.yaml | colibri-imx6ull | pantavisor-starter |
release/docker-armv8-scarthgap.yaml | docker-armv8 | pantavisor-appengine-distro |
release/docker-x86_64-scarthgap.yaml | docker-x86_64 | pantavisor-appengine-distro |
release/imx8mm-var-dart-scarthgap.yaml | imx8mm-var-dart | pantavisor-starter |
release/imx8mn-var-som-scarthgap.yaml | imx8mn-var-som | pantavisor-starter |
release/imx8qxp-b0-mek-scarthgap.yaml | imx8qxp-b0-mek | pantavisor-starter |
release/radxa-rock5a-scarthgap.yaml | rock-5a | pantavisor-starter |
release/raspberrypi-armv8-scarthgap.yaml | raspberrypi-armv8 | pantavisor-starter |
release/rockchip-orangepi-5b-scarthgap.yaml | orangepi-5b | pantavisor-starter |
release/rpi-scarthgap.yaml | raspberrypi | pantavisor-starter |
release/sunxi-bananapi-m2-berry-scarthgap.yaml | bananapi-m2-berry | pantavisor-starter |
release/sunxi-orange-pi-3lts-scarthgap.yaml | orange-pi-3lts | pantavisor-starter |
release/sunxi-orange-pi-r1-scarthgap.yaml | orange-pi-r1 | pantavisor-starter |
release/verdin-imx8mm-scarthgap.yaml | verdin-imx8mm | pantavisor-starter |
The release/*.yaml Target column shows pantavisor-starter, but the
factory-flash machines also build pv-flash-bundle (and, for Toradex, the
mc:tezi-recovery:u-boot-toradex multiconfig). Those extras are declared per
machine as extra_targets in .github/machines.json and appended to the
target: list by .github/scripts/makemachines — there is no dedicated
build-base-*-starter.yaml for them.
Multiconfig Architecture
When using bsp-multi.yaml, builds use three separate multiconfigs to avoid TMPDIR conflicts:
| Multiconfig | Purpose | Config file |
|---|---|---|
default | Main image build | — |
pv-initramfs-panta | Initramfs with musl libc | conf/multiconfig/pv-initramfs-panta.conf |
pv-panta | Container builds | conf/multiconfig/pv-panta.conf |
Each multiconfig uses a separate TMPDIR, set in its conf file:
# conf/multiconfig/pv-initramfs-panta.conf
TMPDIR = "${TOPDIR}/tmp-${DISTRO_CODENAME}-pv-initramfs-panta"
# conf/multiconfig/pv-panta.conf
TMPDIR = "${TOPDIR}/tmp-${DISTRO_CODENAME}-pv-panta"
(Only the Raspberry Pi kernel-variant multiconfigs append ${MACHINE} — see below.)
PANTAVISOR_FEATURES
Controls which optional Pantavisor components are compiled in and installed. Defined in classes/pvbase.bbclass. The table below lists the commonly used features, not an exhaustive set:
| Feature | Description |
|---|---|
dm-crypt | Storage encryption |
dm-verity | Container rootfs integrity verification |
autogrow | Automatic partition growing |
runc | OCI runtime support |
tailscale | Tailscale VPN integration |
debug | Debug features |
pvcontrol | pv-ctrl socket and CLI tools (pvcurl, pvcontrol) |
xconnect | Service mesh for container-to-container communication |
xconnect-dbus-systembus | D-Bus system bus support for xconnect |
container-mdev | Per-container mdev device-node hook (runs an mdev LXC mount hook on each container start) |
rngdaemon | Random number generator daemon |
squash-lz4 | LZ4 squashfs compression |
squash-zstd | Zstd squashfs compression |
rpi-tryboot | Raspberry Pi A/B boot partition support |
bootchartd | Boot timing analysis (writes to /; use rdinit=/sbin/bootchartd) |
lxc-stable | LXC 6.x (lxc6-pv), the default LXC runtime; on by default |
lxc-next | LXC 7.x (lxc7-pv) instead of LXC 6.x; needs Linux 5.12+ and a cgroup v2 host; also available as the kas/with-lxc-next.yaml fragment |
lxc-deprecated | The old LXC 3.x (lxc-pv) instead of LXC 6.x; wins over lxc-next if both are set; also available as the kas/with-lxc-deprecated.yaml fragment |
wakelocks | PM wakelocks + autosleep — adds the wakelock.cfg kernel fragment (see pantavisor wakelocks) |
console-logging | Boot console logging on Raspberry Pi images |
automod | Automatic kernel module loading (kmod in the initramfs) |
caam-nxp | NXP CAAM secure key support (caam-nxp.cfg kernel fragment, keyctl-caam) |
dcp | NXP DCP hardware-bound trusted keys (i.MX6ULL kernel patches, keyutils) |
debug-hooks | Debug hook scripts (-DPANTAVISOR_DEBUG_HOOKS=ON) |
appengine | Container-hosted appengine build (-DPANTAVISOR_APPENGINE=ON); appended by the panta-appengine distro |
pv-manifest-audit / pv-manifest-strict | Manifest audit of the built image; strict fails the build on a mismatch |
Default: dm-crypt dm-verity autogrow runc tailscale debug rngdaemon pvcontrol xconnect xconnect-dbus-systembus container-mdev lxc-stable
Caution:
rngdaemonappears in the default string, but nothing in the layer gates on that token —pantavisor-initramfs.bbchecks for a feature namedrngdinstead. Appendrngdexplicitly if you need the RNG daemon.
Selecting the LXC runtime
lxc-stable (LXC 6) is the default. To build with LXC 7 or the old LXC 3,
add the matching fragment to the kas config chain:
# LXC 7 (lxc7-pv)
./kas-container build kas/build-configs/release/docker-x86_64-scarthgap.yaml:kas/with-lxc-next.yaml
# LXC 3 (lxc-pv)
./kas-container build kas/build-configs/release/docker-x86_64-scarthgap.yaml:kas/with-lxc-deprecated.yaml
or append the feature in a config: PANTAVISOR_FEATURES:append = " lxc-next".
classes/pvbase.bbclass turns the feature into PV_LXC_RECIPE, which
pantavisor and pv-sdk depend on. kas menu offers the same choice under
"Optional overlays".
Selecting the cgroup version
Device images tell Pantavisor which cgroup layout to use through
PV_SYSTEM_CGROUP_VERSION in /etc/pantavisor.config. The default follows
the LXC runtime and comes from PANTAVISOR_CGROUP_VERSION
(classes/pvbase.bbclass):
| LXC runtime | Default | Why |
|---|---|---|
lxc-stable (LXC 6) | auto | Pantavisor picks cgroup2 at boot if the kernel can do it, otherwise cgroup v1 with a deprecation warning |
lxc-next (LXC 7) | 2 | LXC 7 has no cgroup v1 support |
lxc-deprecated (LXC 3) | 1 | LXC 3 only supports the hybrid layout (deprecated) |
The layer adds no kernel options for this; the kernel config stays the
machine/BSP decision. cgroup2 device control needs a cgroup BPF program, so
a kernel used with 2 must have CONFIG_BPF_SYSCALL=y and
CONFIG_CGROUP_BPF=y. When the value resolves to 2, the kernel build
checks this after do_configure and stops if either is missing:
ERROR: linux-raspberrypi-6.6.x-r0 do_pv_check_cgroup_bpf: PV_SYSTEM_CGROUP_VERSION=2 needs cgroup BPF for container device control, but the kernel config lacks: CONFIG_BPF_SYSCALL=y, CONFIG_CGROUP_BPF=y.
Either enable them in the BSP kernel config, or set PANTAVISOR_CGROUP_VERSION = "1" (or "auto").
Fix it by enabling the options in the BSP kernel config (for example a
.cfg fragment in your kernel bbappend), or by choosing another version.
Kernels that are not built (linux-dummy, used by the docker machines) are
not checked. Change the version for one machine in a distro or machine
config:
PANTAVISOR_CGROUP_VERSION:my-machine = "1"
or for every image, through the per-key override (it wins over the default):
PANTAVISOR_CONFIG[PV_SYSTEM_CGROUP_VERSION] = "1"
Check the result in the built rootfs:
grep PV_SYSTEM_CGROUP_VERSION /etc/pantavisor.config
See Pantavisor cgroups for what each value does at boot. The appengine does not use this default.
The += vs :append Pitfall
pvbase.bbclass sets defaults via ??= (weak default operator):
PANTAVISOR_FEATURES ??= " dm-crypt dm-verity autogrow runc tailscale debug rngdaemon pvcontrol xconnect xconnect-dbus-systembus container-mdev lxc-stable "
In distro includes, you must use :append or :remove — never +=:
# WRONG — clobbers ??= defaults, silently drops xconnect, pvcontrol, rngdaemon
PANTAVISOR_FEATURES += "appengine"
# CORRECT — preserves ??= defaults and appends
PANTAVISOR_FEATURES:append = " appengine"
TLS Trust Store
Pantavisor checks the TLS certificates of the HTTPS servers it connects to,
such as Pantahub, against the root certificates in /etc/thttp/certs
(config key PV_LIBTHTTP_CERTSDIR). The libthttp-certs package fills that
directory from the Mozilla bundle in ca-certificates, keeping only the roots
of six large public CAs: Let's Encrypt (ISRG), DigiCert, Sectigo, GlobalSign,
Google Trust Services and Amazon.
The list is the PV_TLS_CA_CERTS variable in
recipes-pv/libthttp/libthttp_git.bb. Each entry is a file name from
/usr/share/ca-certificates/mozilla/, without .crt. To add a root, append
it from a kas local_conf_header or a bbappend:
PV_TLS_CA_CERTS:append = " Microsoft_RSA_Root_Certificate_Authority_2017"
A name that is not in the bundle is skipped with a build warning, so a
ca-certificates update that retires an old root does not break the build.
Every file in the directory must parse with the mbedtls build Pantavisor uses
(RSA, or ECDSA on P-256/P-384; no RSA-PSS): one bad file makes Pantavisor
refuse the whole directory.
To check what a device trusts:
ls /etc/thttp/certs
grep truststore /pv/logs/<revision>/pantavisor/pantavisor.log
Raspberry Pi Tryboot (rpi-tryboot)
The rpi-tryboot feature enables A/B boot partition support for Raspberry Pi, building a unified boot image supporting all RPi variants from a single build.
Configuration: kas/machines/rpi.yaml
Kernel Variant Multiconfigs
| Multiconfig | Machine | Target |
|---|---|---|
rpi-kernel.conf | raspberrypi | Pi 0/1 |
rpi-kernel7.conf | raspberrypi2 | Pi 2/3 32-bit |
rpi-kernel7l.conf | raspberrypi-armv7 | Pi 4 32-bit |
rpi-kernel8.conf | raspberrypi-armv8 | Pi 3/4 64-bit |
rpi-kernel_2712.conf | raspberrypi5 | Pi 5 |
Each uses a separate TMPDIR: tmp-${DISTRO_CODENAME}-rpi-kernel-${MACHINE}.
Key Recipes
dynamic-layers/meta-raspberrypi/recipes-pv/images/rpi-boot-image.bb— FAT32 boot partition with all kernel variantsdynamic-layers/meta-raspberrypi/recipes-pv/images/rpi-bootsel.bb— Boot selector partition withautoboot.txt- WKS file:
wic/rpi-tryboot-ab.wks
Partition Layout
Partition 1 (bootsel): FAT16 — autoboot.txt, bootcode.bin (A/B selector)
Partition 2 (boot_a): FAT32 — kernels, DTBs, config.txt, initramfs
Partition 3 (boot_b): FAT32 — same as boot_a (for A/B switching)
Partition 4 (root): ext4 — rootfs with /trails/0 pvr state
Output Artifacts
These are packed into the bsp/ directory of the BSP pvrexport state (by
pantavisor-bsp.bb), not shipped as standalone deploy files:
pantavisor-rpi.img.gz— Gzipped boot partitionmodules_<version>.squashfs— Per-kernel-version modules (e.g.modules_6.6.63-v8+.squashfs)firmware.squashfs— Shared firmware
Output Artifacts
Build outputs are in build/tmp-{codename}/deploy/images/{machine}/:
| Artifact | Description |
|---|---|
*.pvrexport.tgz | Pantavisor export bundles (main deployment artifact) |
*.wic / *.wic.bz2 | Complete disk images |
pantavisor-initramfs-*.cpio.gz | Initramfs image |
pantavisor-appengine-docker.tar | Docker image for manual appengine testing |
pantavisor-appengine-distro-docker-x86_64-*.tar.gz | Self-contained test bundle: Docker images + test.docker.sh runner |
BSP update source and build metadata (bsp/src.json, bsp/build.json)
pantavisor-bsp.bb writes two informational files into the BSP state.
Pantavisor skips both when it parses a revision.
bsp/src.json says where to get a newer BSP. It is excluded from the BSP
signature, and it holds #spec (bsp-manifest-src@1) plus, when
PV_BSP_SRC_PVR is set, a pvr key pointing at a pvr repo that always holds
the latest BSP for the machine, such as a Pantahub trail:
PV_BSP_SRC_PVR = "https://pvr.pantahub.com/<owner>/<trail>"
{
"#spec": "bsp-manifest-src@1",
"pvr": "https://pvr.pantahub.com/<owner>/<trail>#bsp,_sigs/bsp.json,device.json"
}
The parts after # come from PV_BSP_SRC_PVR_PARTS. They include the BSP
signature, so an update brings the signature that covers the new files. In a
pvr checkout of a device, fetch the latest BSP from that source with:
pvr app update bsp
PV_BSP_SRC_PVR is empty by default, so src.json has no pvr key and there
is nothing to update from until a release channel is published.
bsp/build.json records what the BSP was built from. It is covered by the
BSP signature. pvr app update bsp keeps only the keys it knows in src.json,
which is why this lives in a separate file.
| Key | Content |
|---|---|
gitdescribe, platform, target, pvrversion | The keys the pv-manifest CI wrote: DISTRO_VERSION, MACHINE, TARGET_SYS and pvr version <N>. The Pantahub device page reads them, and fails to render a BSP without them |
pv_build_origin | yocto |
bsp | name (<PN>-<MACHINE>-<TCLIBC>, e.g. pantavisor-bsp-colibri-imx6ull-musl), machine, architecture, version (DISTRO_VERSION), distro, yocto_release, pantavisor_features |
kernel | provider and versions: one entry per shipped kernel, so several on rpi-tryboot and none on linux-dummy |
toolchain | compiler_version (first line of ${CC} --version), libc (TCLIBC) and target triplet |
layers | branch, revision and modified for each layer in BBLAYERS |
packages | Name and version of every package in the initramfs |
updates | releases, source and docs URLs |
Read it from a build's export, or from a running device:
# on the build host
tar xzOf build/tmp-scarthgap/deploy/images/<machine>/pantavisor-bsp-<machine>.pvrexport.tgz json \
| jq '."bsp/build.json".kernel'
# on the device, inside the state.json of the running revision
pvcontrol steps get current
{
"provider": "linux-toradex-upstream",
"versions": [
"6.6.157-0"
]
}
A downstream BSP points updates at its own release channel by setting
PV_BSP_UPDATES_RELEASES, PV_BSP_UPDATES_SOURCE and PV_BSP_UPDATES_DOCS.
Supported Yocto Releases
| Release | Status |
|---|---|
| scarthgap | Primary (CI-tested) |
| kirkstone | Supported (LTS) |
Both scarthgap and kirkstone are Yocto LTS releases.
Layer compatibility is declared in conf/layer.conf:
LAYERSERIES_COMPAT_meta-pantavisor = "kirkstone scarthgap"
Key Build Paths
| Path | Description |
|---|---|
build/workspace/sources/pantavisor/ | Pantavisor source (workspace builds) |
build/tmp-scarthgap/deploy/images/ | Build outputs |
recipes-containers/pv-examples/ | Example container recipes |
kas/build-configs/release/ | KAS release machine configurations |