Skip to main content
Version: master

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​

RecipeDescription
recipes-pv/pantavisor/pantavisor_git.bbCore Pantavisor runtime (C, cmake-based); SRCREV forwarded from pantavisor.inc
recipes-pv/images/pantavisor-initramfs.bbInitramfs image
recipes-pv/images/pantavisor-bsp.bbBSP image (generates pvrexport bundles)
recipes-pv/images/pantavisor-starter.bbFlashable starter disk image (.wic)
recipes-pv/pvr/pvr_*.bbPVR CLI tool (Go-based)
recipes-pv/lxc6-pv/lxc6-pv_git.bbPantavisor-specific LXC 6 fork (default, lxc-stable)
recipes-pv/lxc7-pv/lxc7-pv_git.bbPantavisor-specific LXC 7 fork (lxc-next)
recipes-pv/lxc-pv/lxc-pv_git.bbPantavisor-specific LXC 3 fork (lxc-deprecated)

BitBake Classes​

ClassDescription
classes/pvbase.bbclassDefines PANTAVISOR_FEATURES variable and defaults
classes/pvrexport.bbclassPVR export functionality for images
classes/container-pvrexport.bbclassContainer pvrexport packaging
classes/pvr-ca.bbclassCertificate authority handling
classes/pvroot-image.bbclassRoot container image support

KAS Configuration Hierarchy​

KAS is the primary build system. Configuration is composed by layering YAML fragments:

FileDescription
kas/bsp-base.yamlBase configuration for BSP builds; defines repos and core settings
kas/bsp-multi.yamlMulticonfig builds (separate configs for initramfs and containers)
kas/scarthgap.yaml / kas/kirkstone.yamlYocto release-specific patches and branches
kas/machines/*.yamlPer-machine configurations
kas/platforms/*.yamlPlatform-specific layer includes (sunxi, raspberrypi, etc.)
kas/with-workspace.yamlOverlay 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.

ConfigMachineTarget
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.yamlorangepi-i96pantavisor-starter
release/colibri-imx6ull-scarthgap.yamlcolibri-imx6ullpantavisor-starter
release/docker-armv8-scarthgap.yamldocker-armv8pantavisor-appengine-distro
release/docker-x86_64-scarthgap.yamldocker-x86_64pantavisor-appengine-distro
release/imx8mm-var-dart-scarthgap.yamlimx8mm-var-dartpantavisor-starter
release/imx8mn-var-som-scarthgap.yamlimx8mn-var-sompantavisor-starter
release/imx8qxp-b0-mek-scarthgap.yamlimx8qxp-b0-mekpantavisor-starter
release/radxa-rock5a-scarthgap.yamlrock-5apantavisor-starter
release/raspberrypi-armv8-scarthgap.yamlraspberrypi-armv8pantavisor-starter
release/rockchip-orangepi-5b-scarthgap.yamlorangepi-5bpantavisor-starter
release/rpi-scarthgap.yamlraspberrypipantavisor-starter
release/sunxi-bananapi-m2-berry-scarthgap.yamlbananapi-m2-berrypantavisor-starter
release/sunxi-orange-pi-3lts-scarthgap.yamlorange-pi-3ltspantavisor-starter
release/sunxi-orange-pi-r1-scarthgap.yamlorange-pi-r1pantavisor-starter
release/verdin-imx8mm-scarthgap.yamlverdin-imx8mmpantavisor-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:

MulticonfigPurposeConfig file
defaultMain image build—
pv-initramfs-pantaInitramfs with musl libcconf/multiconfig/pv-initramfs-panta.conf
pv-pantaContainer buildsconf/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:

FeatureDescription
dm-cryptStorage encryption
dm-verityContainer rootfs integrity verification
autogrowAutomatic partition growing
runcOCI runtime support
tailscaleTailscale VPN integration
debugDebug features
pvcontrolpv-ctrl socket and CLI tools (pvcurl, pvcontrol)
xconnectService mesh for container-to-container communication
xconnect-dbus-systembusD-Bus system bus support for xconnect
container-mdevPer-container mdev device-node hook (runs an mdev LXC mount hook on each container start)
rngdaemonRandom number generator daemon
squash-lz4LZ4 squashfs compression
squash-zstdZstd squashfs compression
rpi-trybootRaspberry Pi A/B boot partition support
bootchartdBoot timing analysis (writes to /; use rdinit=/sbin/bootchartd)
lxc-stableLXC 6.x (lxc6-pv), the default LXC runtime; on by default
lxc-nextLXC 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-deprecatedThe 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
wakelocksPM wakelocks + autosleep — adds the wakelock.cfg kernel fragment (see pantavisor wakelocks)
console-loggingBoot console logging on Raspberry Pi images
automodAutomatic kernel module loading (kmod in the initramfs)
caam-nxpNXP CAAM secure key support (caam-nxp.cfg kernel fragment, keyctl-caam)
dcpNXP DCP hardware-bound trusted keys (i.MX6ULL kernel patches, keyutils)
debug-hooksDebug hook scripts (-DPANTAVISOR_DEBUG_HOOKS=ON)
appengineContainer-hosted appengine build (-DPANTAVISOR_APPENGINE=ON); appended by the panta-appengine distro
pv-manifest-audit / pv-manifest-strictManifest 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: rngdaemon appears in the default string, but nothing in the layer gates on that token — pantavisor-initramfs.bb checks for a feature named rngd instead. Append rngd explicitly 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 runtimeDefaultWhy
lxc-stable (LXC 6)autoPantavisor picks cgroup2 at boot if the kernel can do it, otherwise cgroup v1 with a deprecation warning
lxc-next (LXC 7)2LXC 7 has no cgroup v1 support
lxc-deprecated (LXC 3)1LXC 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​

MulticonfigMachineTarget
rpi-kernel.confraspberrypiPi 0/1
rpi-kernel7.confraspberrypi2Pi 2/3 32-bit
rpi-kernel7l.confraspberrypi-armv7Pi 4 32-bit
rpi-kernel8.confraspberrypi-armv8Pi 3/4 64-bit
rpi-kernel_2712.confraspberrypi5Pi 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 variants
  • dynamic-layers/meta-raspberrypi/recipes-pv/images/rpi-bootsel.bb — Boot selector partition with autoboot.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 partition
  • modules_<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}/:

ArtifactDescription
*.pvrexport.tgzPantavisor export bundles (main deployment artifact)
*.wic / *.wic.bz2Complete disk images
pantavisor-initramfs-*.cpio.gzInitramfs image
pantavisor-appengine-docker.tarDocker image for manual appengine testing
pantavisor-appengine-distro-docker-x86_64-*.tar.gzSelf-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.

KeyContent
gitdescribe, platform, target, pvrversionThe 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_originyocto
bspname (<PN>-<MACHINE>-<TCLIBC>, e.g. pantavisor-bsp-colibri-imx6ull-musl), machine, architecture, version (DISTRO_VERSION), distro, yocto_release, pantavisor_features
kernelprovider and versions: one entry per shipped kernel, so several on rpi-tryboot and none on linux-dummy
toolchaincompiler_version (first line of ${CC} --version), libc (TCLIBC) and target triplet
layersbranch, revision and modified for each layer in BBLAYERS
packagesName and version of every package in the initramfs
updatesreleases, 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​

ReleaseStatus
scarthgapPrimary (CI-tested)
kirkstoneSupported (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​

PathDescription
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