Crate supermachine_kernel

Expand description

Pre-built runtime assets for supermachine, packaged as a Rust crate so embedders can cargo add supermachine-kernel instead of fetching binaries out of band — with no network at build time (the bytes are include_bytes!’d into the binary).

§A facade over per-arch sub-crates

supermachine runs a guest Linux kernel matching the host arch (KVM on x86_64 runs an x86_64 guest; HVF on Apple Silicon runs an aarch64 guest). Shipping every arch’s kernel in one crate would bust the crates.io ~10 MiB cap and make every consumer download kernels they can’t use.

So this crate is a thin facade. The actual bytes live in per-arch sub-crates, declared as [target.'cfg(target_arch = ...)'] dependencies:

supermachine-kernel-aarch64 — aarch64 Image + init-oci + agent + smpark.ko
supermachine-kernel-x86-64 — x86_64 bzImage + busybox + agent

Cargo only resolves/downloads the dependency whose cfg(target_arch) matches the compilation target, so building for x86_64 fetches only the x86 sub-crate, and aarch64 fetches only the arm one — never the other arch’s multi-MiB kernel. This module re-exports the matching sub-crate’s public API (KERNEL_BYTES, extract_kernel_to, …) so callers write arch-agnostic code:

// Same call on any host; you get that host's guest kernel.
supermachine_kernel::extract_kernel_to(
    std::path::Path::new("/tmp/supermachine/kernel"),
).unwrap();

§Arch-specific surface

Most of the API is common to both sub-crates: KERNEL_BYTES / KERNEL_LEN, SUPERMACHINE_AGENT_BYTES / _LEN, and the extract_kernel_to{,_with_parents} / extract_supermachine_agent_to{,_with_parents} helpers.

Some items exist only on one arch because the backends differ:

aarch64 only: INIT_OCI_BYTES, SMPARK_KO_BYTES (+ their extract_* / _LEN). The HVF backend uses an init-oci PID-1 shim and an smpark.ko module for multi-vCPU snapshot capture.
x86_64 only: BUSYBOX_BYTES (+ extract_busybox_to* / BUSYBOX_LEN). The KVM backend builds the container rootfs (overlayfs + switch_root) directly in the agent initramfs, using a bundled busybox.

Code that needs an arch-specific item should gate it with #[cfg(target_arch = "…")] to stay portable.

Constants§

BUSYBOX_BYTES: Raw bytes of the static x86_64 busybox staged into the agent initramfs. The generated PID-1 init uses it for the overlayfs + switch_root dance that builds the writable container rootfs from the read-only OCI squashfs.
BUSYBOX_LEN: Length of the busybox binary in bytes.
KERNEL_BYTES: Raw bytes of the x86_64 kernel — a minimal-config Linux bzImage.
KERNEL_LEN: Length of the kernel image in bytes — KERNEL_BYTES.len(), const-evaluable.
SUPERMACHINE_AGENT_BYTES: Raw bytes of the in-VM supermachine-agent (static x86_64-musl ELF). Runs as PID 1 inside the container post-switch_root, serving docker-style exec and other control RPCs over vsock.
SUPERMACHINE_AGENT_LEN: Length of the supermachine-agent binary in bytes.

Functions§

extract_busybox_to: Write the bundled busybox to dest, executable (mode 0o755) on Unix.
extract_busybox_to_with_parents: Like extract_busybox_to but mkdir -p’s the parent dir first.
extract_kernel_to: Write the bundled kernel image to dest. Overwrites any existing file; the parent dir must exist (use extract_kernel_to_with_parents to mkdir).
extract_kernel_to_with_parents: Like extract_kernel_to but mkdir -p’s the parent dir first.
extract_supermachine_agent_to: Write the bundled supermachine-agent to dest, executable on Unix.
extract_supermachine_agent_to_with_parents: Like extract_supermachine_agent_to but mkdir -p’s the parent first.