Phase 211 — first kernel + initramfs payload

At a glance

Field	Value
Phase family	Phase 2 — bootable image
Run command	`make phase 211`
Underlying make target/script	`vm/phase2/build-image-skeleton.sh --kernel-payload`
Runs on	host with rootful image mount work
Main proof/artifact	Installs the first kernel/initramfs payload into /boot/ONIX/ inside the image.

Phase 211 installs the first real files at the paths that Phase 206 and Phase 207 already promised:

/boot/ONIX/vmlinuz
/boot/ONIX/initramfs.img

This is the first time the ONIX image contains a kernel and initramfs payload.

What a payload is

A payload is the thing a previous layer hands to the next layer.

For this part of boot:

systemd-boot payload -> Linux kernel + initramfs
Linux kernel payload -> mounted root filesystem
root filesystem payload -> /usr/lib/systemd/systemd
systemd payload -> services

So Phase 211 is not “the whole OS boots now”.

Phase 211 only gives systemd-boot something real to load.

Where the first payload comes from

The default Phase 211 source is:

vm/state/vmlinuz-virt
vm/state/initramfs-virt

Those files are exported by the forge disk build in Phase 0.

That makes them a temporary bootstrap source, not the final ONIX kernel package story.

The final shape is still:

onix-kernel
onix-initramfs

But using the exported forge payload is useful because it is already known to be a QEMU-capable kernel/initramfs pair.

Why Phase 211 checks the initramfs

ONIX root is XFS:

LABEL=onix-root  /  xfs

That means the initramfs must understand XFS before the kernel can mount /.

If the initramfs cannot mount /, the boot fails before systemd even has a chance to start.

So make phase 211 checks the initramfs contents before copying it.

It requires:

/init
xfs.ko
vfat.ko
virtio_blk.ko

Those mean:

item	why it matters
`/init`	the first program inside the initramfs
`xfs.ko`	lets early boot mount the ONIX XFS root
`vfat.ko`	lets early boot understand FAT boot files if needed
`virtio_blk.ko`	lets early boot see the QEMU virtio disk

If the current exported forge initramfs is old, Phase 211 may stop with:

initramfs lacks xfs.ko

That is good. It means the verifier prevented us from installing a boot payload that cannot mount the ONIX root filesystem.

The forge setup now requests XFS support when it creates the exported initramfs, so rebuilding the forge disk produces a better payload.

What Phase 211 writes

make phase 211 mounts the existing ONIX image and writes:

/boot/ONIX/vmlinuz
/boot/ONIX/initramfs.img
/boot/ONIX/README.phase211
/boot/loader/entries/onix-phase-211.conf
/efi/loader/loader.conf

The BLS entry becomes:

title ONIX
sort-key onix
version phase-211
linux /ONIX/vmlinuz
initrd /ONIX/initramfs.img
options root=LABEL=onix-root rootfstype=xfs rw init=/usr/lib/systemd/systemd systemd.unit=multi-user.target console=tty0 console=ttyS0,115200

The important new part is not the path. The path already existed in the contract.

The important new part is that the files now exist and match the selected source payload byte-for-byte.

What Phase 211 verifies

make phase 211 verifies:

the Phase 207 kernel/initramfs contract still exists
the source kernel file exists and is non-empty
the source initramfs exists and is non-empty
the initramfs can be listed
the initramfs contains /init
the initramfs contains xfs.ko
the initramfs contains vfat.ko
the initramfs contains virtio_blk.ko
the Phase 206 boot skeleton exists first
/boot/ONIX/vmlinuz is installed
/boot/ONIX/initramfs.img is installed
the installed files match the source files
the default boot entry is onix-phase-211.conf
the boot entry still points to /usr/lib/systemd/systemd
the image still does not contain systemd userspace yet

What Phase 211 does not prove

Phase 211 does not prove:

the kernel boots
the initramfs mounts the root filesystem
systemd exists
systemd starts
QEMU reaches login

That is why Phase 212 is still needed.

Keyboard shortcuts

ONIX Book