update docs

docs/developer/m4-work.md

@@ -0,0 +1,60 @@
+# M4 boot integration development record
+
+Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
+
+
+The user has authorized the remaining software through M12. This page records
+M4 development decisions. Software validation is complete; see [M4 evidence](m4-validation.md). Physical Pi validation remains deferred.
+
+The Pi kernel overlay starts from the exact source commit and archive checksum in
+Void's pinned `rpi5-kernel` recipe (6.12.87). It uses `bcm2712_defconfig` plus the
+small FDS delta, verifies Kconfig actually applied that delta, and exports the Pi 5
+Image, DTBs, overlays, and modules without modifying upstream Void files.
+The upstream Pi 5 16 KiB page configuration is retained.
+
+Critical storage, EROFS, keyboard, console and VC4 display support are built in.
+VC4 also requires the SND/SND_SOC core to be built in; optional sound devices can
+remain modules. CH341 SPI is disabled for the Dasung companion bridge. Generic
+ARM VM drivers are built into this same kernel so we can exercise software boot
+without claiming to emulate Pi firmware or RP1. Debug/BTF artifacts are omitted;
+module authentication is part of immutable image/release authentication rather
+than random build-generated module keys.
+
+`make kernel` uses the existing Void build container and cross compiler. Its
+additional host dependencies are Perl and Python for kernel generation, bc for
+build-time arithmetic, Bison/Flex for Kconfig, kmod for module indexes, OpenSSL
+headers for kernel build utilities, and archive tools. OpenSSL is a host build
+dependency, not a new Rust runtime dependency. The source and checksum are recorded
+in `packages/fds-kernel/template`.
+
+Image builders use a separate project-local prefix at `.host/image-tools` for
+signed Void x86_64 `erofs-utils`, `dosfstools` and `mtools`, plus their resolved
+libraries. They create filesystem images without privileged loop mounts and do
+not mutate the shared kernel build container. Versions and cached inputs are
+recorded under `out/manifests/image-tool-*`; full input locking is M12 work.
+
+Stage0 now has a Rust PID-1 implementation: direct filesystem
+syscalls, authenticated kernel uevents, explicit normal/recovery partition
+selection, early Dasung supervision, EROFS validation, mount transfer, and exec
+of native s6. Its normal path refuses to run outside root PID 1 on ramfs/tmpfs.
+The implementation reuses the locked `libc` crate for these Linux syscalls.
+The full initramfs matrix passed all four formats, missing-media USB insertion,
+ambiguous SYSTEM recovery, explicit recovery, invalid filesystems and foreign
+root rejection. A refreshed base package/rootfs build is being completed.
+QEMU uses its `max` CPU because the retained 16 KiB Pi kernel cannot execute
+on the old Cortex-A72 VM model.
+
+The FAT32 boot builder verifies every file after reading it back with mtools.
+Directory timestamps are normalized as well as file timestamps; two consecutive
+builds from the same inputs produced the same complete image SHA-256. This narrow
+result is not a claim of complete offline or release reproducibility.
+Two complete kernel builds also produced identical kernel Image, Pi 5 DTB and
+XBPS package digests. The helper now reuses a build after checking recorded
+source inputs, its package and all exported files. `--rebuild` bypasses reuse.
+
+The [boot guide](boot.md) documents usable build commands, image boundaries,
+waiting-console commands, display policy, and remaining physical checks.
+
+References: [Raspberry Pi cross-compilation](https://www.raspberrypi.com/documentation/computers/linux_kernel.html#cross-compile-the-kernel),
+[Linux initramfs](https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html),
+and [root handoff semantics](https://man7.org/linux/man-pages/man8/switch_root.8.html).