removing the need for panic and _start snippets in user space binaries

build.zig

@@ -54,6 +54,12 @@ fn timestamp(b: *std.Build) []const u8 {
 /// can't reach), linked against the `runtime` runtime library with the shared user
 /// link script. Pinned to LLVM + LLD so the script's PHDRS (segment permissions)
 /// are authoritative — the kernel's W^X user-ELF loader requires exact perms.
+///
+/// The compilation root is not the program's own file but the shared shim
+/// library/runtime/root.zig, which supplies the root declarations (`main`
+/// re-export, panic handler, `_start` pull) so a program only defines
+/// `pub fn main`. The program's file becomes the `program` module the shim
+/// imports; reach it through `programModule` to add per-binary imports.
 fn addUserBinary(
     b: *std.Build,
     target: std.Build.ResolvedTarget,
@@ -64,10 +70,26 @@ fn addUserBinary(
     name: []const u8,
     root: []const u8,
 ) *std.Build.Step.Compile {
+    // Settings (target, optimize, code model, ...) live on the root module only;
+    // the program and runtime modules leave theirs null and inherit them.
+    const program_module = b.createModule(.{
+        .root_source_file = b.path(root),
+        .imports = &.{
+            .{ .name = "runtime", .module = runtime_module },
+            // Typed volatile MMIO + memory barriers, for drivers. See library/mmio/.
+            .{ .name = "mmio", .module = mmio_module },
+            // Keyboard layouts (keycode + modifiers -> keysym/character), available
+            // to any program that wants it. See library/xkeyboard-config/.
+            .{ .name = "xkeyboard-config", .module = xkeyboard_config_module },
+            // ACPI/PnP hardware-ID registry, so drivers name devices
+            // (HardwareId.ps2_keyboard) instead of magic "_HID" strings.
+            .{ .name = "acpi-ids", .module = acpi_ids_module },
+        },
+    });
     const exe = b.addExecutable(.{
         .name = name,
         .root_module = b.createModule(.{
-            .root_source_file = b.path(root),
+            .root_source_file = b.path("library/runtime/root.zig"),
             .target = target,
             .optimize = .ReleaseSmall,
             .code_model = .large,
@@ -77,14 +99,7 @@ fn addUserBinary(
             .stack_protector = false,
             .imports = &.{
                 .{ .name = "runtime", .module = runtime_module },
-                // Typed volatile MMIO + memory barriers, for drivers. See library/mmio/.
+                .{ .name = "program", .module = program_module },
-                .{ .name = "mmio", .module = mmio_module },
-                // Keyboard layouts (keycode + modifiers -> keysym/character), available
-                // to any program that wants it. See library/xkeyboard-config/.
-                .{ .name = "xkeyboard-config", .module = xkeyboard_config_module },
-                // ACPI/PnP hardware-ID registry, so drivers name devices
-                // (HardwareId.ps2_keyboard) instead of magic "_HID" strings.
-                .{ .name = "acpi-ids", .module = acpi_ids_module },
             },
         }),
     });
@@ -96,6 +111,14 @@ fn addUserBinary(
     return exe;
 }
 
+/// The `program` module of a binary built by `addUserBinary` — the module rooted
+/// at the program's own source file. Per-binary imports (protocol modules, bus
+/// ABIs) go here, not on the root shim: module imports are not transitive, so an
+/// import added to the root would be invisible to the program's code.
+fn programModule(exe: *std.Build.Step.Compile) *std.Build.Module {
+    return exe.root_module.import_table.get("program").?;
+}
+
 /// The modules the kernel imports, gathered once so both kernel variants (the
 /// installed one and the serial-enabled one `run-x86-64` boots) are built from
 /// the same set. `build_options` is *not* here — it carries `serial`/`test_case`,
@@ -456,20 +479,20 @@ pub fn build(b: *std.Build) void {
     // The xHCI bus driver builds chapter-9 requests and decodes descriptors from
     // usb-abi, and reports each interface's (class,subclass,protocol) identity via
     // usb-ids.packTriple.
-    usb_xhci_bus_exe.root_module.addImport("usb-abi", usb_abi_module);
+    programModule(usb_xhci_bus_exe).addImport("usb-abi", usb_abi_module);
-    usb_xhci_bus_exe.root_module.addImport("usb-ids", usb_ids_module);
+    programModule(usb_xhci_bus_exe).addImport("usb-ids", usb_ids_module);
-    usb_xhci_bus_exe.root_module.addImport("usb-transfer-protocol", usb_transfer_protocol_module);
+    programModule(usb_xhci_bus_exe).addImport("usb-transfer-protocol", usb_transfer_protocol_module);
     // The USB HID class drivers: keyboard and mouse. They own no hardware — each
     // opens its device through runtime.usb (the transfer protocol) and publishes to
     // the input service. They build chapter-9 class requests from usb-abi.
     const usb_hid_keyboard_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-hid-keyboard", "system/drivers/usb-hid/keyboard.zig");
-    usb_hid_keyboard_exe.root_module.addImport("usb-abi", usb_abi_module);
+    programModule(usb_hid_keyboard_exe).addImport("usb-abi", usb_abi_module);
     const usb_hid_mouse_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-hid-mouse", "system/drivers/usb-hid/mouse.zig");
-    usb_hid_mouse_exe.root_module.addImport("usb-abi", usb_abi_module);
+    programModule(usb_hid_mouse_exe).addImport("usb-abi", usb_abi_module);
     // The USB mass-storage class driver: opens its device via runtime.usb, drives it
     // with Bulk-Only Transport + SCSI, and serves the block protocol under `.block`.
     const usb_storage_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-storage", "system/drivers/usb-storage/usb-storage.zig");
-    usb_storage_exe.root_module.addImport("block-protocol", block_protocol_module);
+    programModule(usb_storage_exe).addImport("block-protocol", block_protocol_module);
     // The FAT filesystem server: mounts the block device and serves it into the VFS
     // at /mnt/usb. Its engine (engine.zig / on-disk.zig) is imported relatively.
     const fat_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "fat", "system/services/fat/fat.zig");
@@ -482,7 +505,7 @@ pub fn build(b: *std.Build) void {
     const pci_bus_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "pci-bus", "system/drivers/pci-bus/pci-bus.zig");
     // The PCI bus driver decodes each function's class triple to human names in its
     // boot log (class/subclass/prog-IF), so pull in the shared pci-class reference.
-    pci_bus_exe.root_module.addImport("pci-class", pci_class_module);
+    programModule(pci_bus_exe).addImport("pci-class", pci_class_module);
     // A test fixture, not a real driver: hellos to the device manager, then faults —
     // what the driver-restart scenario drives the crash-loop cap with.
     const crash_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "crash-test", "system/services/crash-test/crash-test.zig");
@@ -501,13 +524,13 @@ pub fn build(b: *std.Build) void {
         .fdt => "system/services/fdt/fdt.zig",
     };
     const discovery_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "discovery", discovery_source);
-    if (discovery == .acpi) discovery_exe.root_module.addImport("aml", aml_module);
+    if (discovery == .acpi) programModule(discovery_exe).addImport("aml", aml_module);
     const device_manager_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-manager", "system/services/device-manager/device-manager.zig");
     // Names the xHCI PCI class triple from the shared taxonomy instead of a bare 0x0C0330.
-    device_manager_exe.root_module.addImport("pci-class", pci_class_module);
+    programModule(device_manager_exe).addImport("pci-class", pci_class_module);
     // The manager matches reported USB interfaces by their (class,subclass,protocol)
     // triple (usbDriverForIdentity), built from the named usb-ids codes.
-    device_manager_exe.root_module.addImport("usb-ids", usb_ids_module);
+    programModule(device_manager_exe).addImport("usb-ids", usb_ids_module);
     // The input service and its exercisers: the fan-out server, a hardware-free synthetic
     // source, and a subscriber that doubles as the `input` test's oracle. See docs/input.md.
     const input_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "input", "system/services/input/input.zig");

library/runtime/root.zig

@@ -0,0 +1,19 @@
+//! The root module every user binary is compiled through (build.zig,
+//! `addUserBinary`). The program's own file is imported as `program`, and this
+//! shim contributes the declarations Zig resolves from the compilation root —
+//! `main` (dispatched by runtime.start) and the panic handler — and pulls in the
+//! `_start` entry shim. A program therefore only defines `pub fn main`; nothing
+//! else is required in its source file.
+
+const runtime = @import("runtime");
+const program = @import("program");
+
+/// Resolved as `@import("root").main` by runtime.start's comptime dispatch.
+pub const main = program.main;
+
+/// The panic handler for every safety check in the image (runtime.start.panic).
+pub const panic = runtime.panic;
+
+comptime {
+    _ = &runtime.start._start; // pull the runtime entry shim into the image
+}

library/runtime/runtime.zig

@@ -4,12 +4,11 @@
 //! shim. It is compiled into each binary (inheriting its `.large` code model and
 //! freestanding target), so all user programs share one implementation.
 //!
-//! A user binary needs three lines:
+//! A user binary only defines a `pub fn main() void` or
-//!   const runtime = @import("runtime");
+//! `pub fn main(init: runtime.process.Init) void` (arguments arrive via `init`).
-//!   pub const panic = runtime.panic;
+//! The panic handler and the `_start` entry pull live in the shared compilation
-//!   comptime { _ = &runtime.start._start; }   // pull the entry shim in
+//! root, library/runtime/root.zig, which build.zig wires around every program —
-//! and a `pub fn main() void` or `pub fn main(init: runtime.process.Init) void`
+//! nothing to declare per source file.
-//! (arguments arrive via `init`).
 
 pub const system = @import("system.zig");
 /// Monotonic time, delays, and deadlines over the kernel clock/sleep/timer syscalls
@@ -65,7 +64,7 @@ pub const scanout_protocol = @import("scanout-protocol");
 /// `std.os.danos` are staged. See docs/zig-self-hosting.md.
 pub const fs = @import("fs.zig");
 
-/// Re-exported so a user binary can `pub const panic = runtime.panic;`.
+/// Re-exported so the root shim (root.zig) can install it as the panic handler.
 pub const panic = start.panic;
 
 /// Process entry types: the `Init` handed to `main`, and its `Arguments`.

library/runtime/start.zig

@@ -1,6 +1,7 @@
 //! The user-space process entry shim. Every user binary roots `_start` here (via
-//! `entry = _start` in build.zig) and forces this file to be analysed with
+//! `entry = _start` in build.zig); the shared compilation root, root.zig, forces
-//! `comptime { _ = &runtime.start._start; }`, so the whole runtime is linked in.
+//! this file to be analysed with `comptime { _ = &runtime.start._start; }`, so
+//! the whole runtime is linked in.
 
 const std = @import("std");
 const system = @import("system.zig");
@@ -36,7 +37,7 @@ export fn rt_start(stack: [*]const u64) callconv(.c) noreturn {
 /// Comptime-dispatch on root.main's signature, in the spirit of std's start.zig:
 /// zero parameters or one `process.Init`; returns void, noreturn, u8, !void, or !u8.
 fn callMain(init: process.Init) u8 {
-    const root = @import("root"); // the user binary's root source file
+    const root = @import("root"); // root.zig, re-exporting the program's main
     const main_information = @typeInfo(@TypeOf(root.main)).@"fn";
 
     const call_arguments = switch (main_information.params.len) {

system/drivers/pci-bus/pci-bus.zig

@@ -263,8 +263,3 @@ pub fn main(init: runtime.process.Init) void {
         .on_message = onMessage,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/drivers/ps2-bus/keyboard.zig

@@ -177,8 +177,3 @@ pub fn main(init: runtime.process.Init) void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/ps2-bus/mouse.zig

@@ -137,8 +137,3 @@ pub fn main(init: runtime.process.Init) void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/ps2-bus/ps2-bus.zig

@@ -308,8 +308,3 @@ pub fn main() void {
         reply_len = handleAttach(receive[0..got.len], got, &reply_buffer);
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/usb-hid/keyboard.zig

@@ -167,8 +167,3 @@ pub fn main(init: runtime.process.Init) void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/usb-hid/mouse.zig

@@ -133,8 +133,3 @@ pub fn main(init: runtime.process.Init) void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/usb-storage/usb-storage.zig

@@ -180,8 +180,3 @@ pub fn main(init: runtime.process.Init) void {
         .on_message = onMessage,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/usb-xhci-bus/usb-xhci-bus.zig

@@ -417,8 +417,3 @@ pub fn main(init: runtime.process.Init) void {
         .on_notification = onNotification,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/drivers/virtio-gpu/virtio-gpu.zig

@@ -615,8 +615,3 @@ pub fn main(init: runtime.process.Init) void {
         .on_message = onMessage,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/acpi/acpi.zig

@@ -694,8 +694,3 @@ fn rd16(bytes: []const u8, off: usize) u64 {
 fn rd32(bytes: []const u8, off: usize) u64 {
     return rd16(bytes, off) | (rd16(bytes, off + 2) << 16);
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/args-echo/args-echo.zig

@@ -48,8 +48,3 @@ pub fn main(init: runtime.process.Init) void {
     len += 1;
     _ = runtime.system.write(buffer[0..len]);
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/crash-test/crash-test.zig

@@ -37,8 +37,3 @@ pub fn main(init: runtime.process.Init) void {
     const poison: *volatile u32 = @ptrFromInt(0xdead0000);
     poison.* = 1; // the restart machinery's fuel: a real segmentation fault
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/device-list/device-list.zig

@@ -81,8 +81,3 @@ pub fn main() void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/device-manager/device-manager.zig

@@ -586,8 +586,3 @@ pub fn main(init: runtime.process.Init) void {
         .on_notification = onNotification,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/display-demo/display-demo.zig

@@ -45,7 +45,6 @@ pub fn main() void {
     var dx: i32 = 8;
     var frame: u32 = 0;
 
-
     var mouse = input.subscribeMouse(); // type: ?input.MouseSubscriber
     if (mouse == null) _ = system.write("display-demo: no mouse; animating without it\n");
 
@@ -85,8 +84,3 @@ fn clamp(v: i32, lo: i32, hi: i32) i32 {
 fn createFailed() void {
     _ = system.write("display-demo: create failed\n");
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/display/display.zig

@@ -455,8 +455,3 @@ pub fn main() void {
         .on_notification = onNotification,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/fat/fat-test.zig

@@ -101,8 +101,3 @@ pub fn main(init: runtime.process.Init) void {
     }
     _ = runtime.system.write("fat-test: root listing was empty\n");
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/fat/fat.zig

@@ -242,8 +242,3 @@ pub fn main() void {
         .on_message = onMessage,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/fdt/fdt.zig

@@ -28,8 +28,3 @@ pub fn main(init: runtime.process.Init) void {
     // supervisor reads a clean exit as "meant to stop" — correct for a
     // placeholder.
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/init/init.zig

@@ -215,8 +215,3 @@ fn shutDown() void {
     // If S5 did not take, init has nothing left to do but idle.
     while (true) runtime.system.sleep(1000);
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/input-source/input-source.zig

@@ -33,8 +33,3 @@ pub fn main() void {
         system.sleep(200);
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/input-test/input-test.zig

@@ -49,8 +49,3 @@ pub fn main() void {
         }
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/input/input.zig

@@ -138,8 +138,3 @@ pub fn main() void {
         reply_len = handle(receive[0..got.len], got, &reply_buffer);
     }
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/log-flush/log-flush.zig

@@ -60,8 +60,3 @@ pub fn main() void {
     var line: [96]u8 = undefined;
     _ = runtime.system.write(std.fmt.bufPrint(&line, "log-flush: wrote {d} bytes to {s}\n", .{ written, log_path }) catch return);
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/process-test/process-test.zig

@@ -178,8 +178,3 @@ pub fn main(init: runtime.process.Init) void {
 
     _ = runtime.system.write("process-test: ok\n");
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start; // pull the runtime entry shim into the image
-}

system/services/shm-client/shm-client.zig

@@ -44,8 +44,3 @@ pub fn main() void {
         _ = system.write("shm: call failed\n");
     };
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/shm-server/shm-server.zig

@@ -42,8 +42,3 @@ fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?ipc.Han
 pub fn main() void {
     runtime.service.run(64, .{ .service = .shm_test, .on_message = onMessage });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/vfs/vfs-test.zig

@@ -60,8 +60,3 @@ pub fn main(init: runtime.process.Init) void {
     }
     _ = runtime.system.write("vfstest: mismatch\n");
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/services/vfs/vfs.zig

@@ -394,8 +394,3 @@ pub fn main() void {
         .on_notification = onNotification,
     });
 }
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}