Hive-M internals

Xilinx ZynqMP, Yocto build (aionyx-image-minimal), RAUC A/B rootfs, uwm updater.

Project layout

Docker volumes

Bind mounts: sw/ → /sw (ro), sources/sdt → /custom_sources/sdt, keys/ → /keys (ro, if present), each clone repo → /custom_sources/<name>.

Init script

Prepended to every containerized hive-m command:

1. Exports BUILDHIVE_VERSION (tool version) via BB_ENV_PASSTHROUGH_ADDITIONS - default version for update/migration archives.
2. First run: repo init -u <yocto_manifests.url> -b <branch>, repo sync.
3. source edf-init-build-env.
4. Reconciles conf/bblayers.conf with layers on disk (removes stale, adds missing).
5. First run only: sets SSTATE_DIR/DL_DIR in local.conf, runs gen-machine-conf parse-sdt --hw-description /custom_sources/sdt --machine-name zynqmp-ntl-hive-m-sdt, creates+adds meta-ntl-hive, sets MACHINE ??= ntl-hive-m.
6. Every run: re-copies /sw/meta-ntl-hive/* into ../sources/meta-ntl-hive/ - layer edits in the project take effect on the next build.
7. Adds/removes the secure-boot.conf require line in local.conf per sw.secure_boot.
8. Rewrites the # >>> buildhive sstate mirror block in local.conf per sw.sstate_mirror; credentials from SSTATE_MIRROR_AUTH env or the secrets server, written to ~/.netrc. Mirror misses fall back to the local ntl_buildhive_sstate cache and a normal build.
9. Rewrites the # >>> buildhive rm_work block: INHERIT += "rm_work" with RM_WORK_EXCLUDE += "linux-xlnx aionyx-image-minimal". Work dirs are deleted after packaging (tmp/ shrinks several times), so devshell/tmp/work inspection only works for the excluded recipes; kernel-devsrc and export sdk (busybox from the image rootfs/) keep working. Existing projects reclaim space on the next build.

Repos in sw.clone are pulled in parallel before the container starts; --no-update skips this.

meta-ntl-hive layer

conf/layer.conf: priority 7, compatible scarthgap, depends on aionyx-hive. IMAGE_INSTALL:append adds extra packages to the image (template: ptp4l-config); edit with buildhive packages add|remove or the GUI Configure page, see commands.md.

conf/machine/ntl-hive-m.conf requires the SDT-generated machine and backs /etc, /opt/ntl, /usr/lib/firmware overlays with /data.

Serial console lock

recipes-bsp/u-boot/u-boot-xlnx/console.cfg + patch 0002-configs-zynqmp-restrict-stored-env-*. Contract consumed by uwm (docs/src/security/serial-console.md in the uwm repo).

FSBL, PMUFW, ATF and U-Boot still print on UART0. Output only, no input path. JTAG not covered.

New password:

SALT=$(openssl rand -hex 4); printf '%s%s' "$SALT" "$PASSWORD" | sha256sum | awk -v s="$SALT" '{print s":"$1}'

Put the result in CONFIG_AUTOBOOT_STOP_STR_SHA256, rebuild u-boot. At the prompt type the password (no echo) during the delay.

SDK image

export sw --image wraps the populate_sdk installer into a standalone container for application developers: no Yocto tree, no buildhive.

Build context is a temp dir under images/ holding only sdk/ and the installer (hardlinked when possible), so the wic files never reach the docker daemon. aionyx-image-minimal.bbappend sets TOOLCHAIN_HOST_TASK (+nativesdk-cmake/ninja/pkgconfig, makes the env script export CMAKE_TOOLCHAIN_FILE), TOOLCHAIN_TARGET_TASK (+kernel-devsrc) and SDKIMAGE_FEATURES = "dev-pkgs" (no dbg-pkgs/src-pkgs, ~1 GB less).

Kernel module: make -C $SDKTARGETSYSROOT/usr/src/kernel M=$PWD modules, see /opt/ntl-sdk/examples/hello-module. Module vermagic matches the kernel of the build the SDK came from; keep SDK version and firmware version paired. kernel-devsrc has no git metadata, so the Dockerfile derives the -g<sha>[-dirty] suffix from usr/lib/modules/<release> and passes it as LOCALVERSION to make prepare (exported in the profile too), failing the build on mismatch.

Usage:

docker run --rm -it -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1          # shell
docker run --rm -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1 make          # one-shot
docker run --rm -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1     sh -c 'cmake -B build -G Ninja && cmake --build build'

GitHub Actions (container: jobs skip the entrypoint, use a login shell):

jobs:
  build:
    runs-on: ubuntu-latest
    container: ghcr.io/nettimelogic/hive-m-sdk:0.5.1
    defaults: { run: { shell: bash -leo pipefail {0} } }
    steps:
      - uses: actions/checkout@v4
      - run: cmake -B build -G Ninja && cmake --build build && ctest --test-dir build

Publish flow: buildhive export sw --push (or --no-build --push on an existing installer) after docker login ghcr.io. Match --version to the firmware release the SDK was built from.

recipes-kernel/linux/linux-xlnx/qemu.cfg adds virtio-mmio/pci, virtio-net/blk/console, 9p and PCI_HOST_GENERIC to the Hive-M kernel. Inert on the board, lets ntl-shell share /src and network under -M virt; virtio-blk is the path to booting sd.wic in qemu later. export sw also copies rootfs/usr/bin/busybox to images/busybox for the guest shell.

Disk layout (rauc-zynqmp.wks)

Kernel development

build kernel-devsrc   ->  /kernel-devsrc volume: kernel source + build tree + env.sh
build module <name>   ->  oot/<name>/*.ko   (scaffolds Kbuild Makefile, builds against /kernel-devsrc)
build kernel-oot      ->  images/Image     (make -j Image modules, no bitbake)
shell --module <name> ->  bash with env.sh sourced, cwd oot/<name>
code                  ->  VS Code attached to dev container (/kernel-devsrc, /oot, /drivers)

env.sh sets ARCH, CROSS_COMPILE and the toolchain PATH. Module sources live in sources/drivers/staging/ntl/<name>/ (from the drivers clone repo). Re-run build kernel-devsrc after kernel config changes.