Skip to content

Boot sources: the loader hands firmware's device paths, the kernel keeps them, userland resolves @boot - #1027

Merged
Japabu merged 4 commits into
mainfrom
usbd-boot-controller
Oct 23, 2026
Merged

Japabu merged 4 commits into
mainfrom
usbd-boot-controller

Conversation

@Japabu

@Japabu Japabu commented Oct 22, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Every metal test image pinned usbd to one boot controller per bench (pci:0c:03:30/8086:a0ed for the T14, pci:0c:03:30/1022:1639@03:00.3 for the AMD bench). With the AMD's stick in its USB-C port (03:00.4), no usbd drove it, no disk was served, and the readback had no Boot: complete.

Rounds 1 and 2 fixed this by having the kernel mark the boot controller in its inventory. The owner's ruling on item 63 moves that interpretation out of the kernel:

  • the loader captures firmware's device path and the provenance of the partitions it used;
  • the kernel keeps bounded, immutable boot information and does not interpret it;
  • userland matches it and selects drivers.

Round 3 implements that division.

Resulting behaviour

  • Loader (loader/src/bootsource.rs). Before boot services end, it captures two sources:

    • loader: the device firmware loaded the loader from, the ESP. ROOT is read off this partition's disk (rootimage::boot_disk).
    • slot: the booted slot's volume. The signed header, kernel, parameter, supervisor and file server come from it. The loader finds it by GUID among every GPT filesystem, so it can be on another device than the loader's. Its own path records that.

    For each source the loader:

    • copies firmware's device path, bounded at 512 bytes;
    • holds the path to one structural check (toyos_devicepath::Path::parse);
    • places the path's last PCI function with GetLocation().

    A source that has no path, a path that is too long or malformed, or no PCI function on its path, is said by name and carried as absent. Nothing is guessed. The loader logs, for example: Boot source: the loader came off PciRoot(0x0)/Pci(0x1,0x0)/NVMe(0x1,00-…)/HD(2,GPT,C3FA1073-…,0x40800,0x11000), on PCI 0000:00:01.0.

  • New pure crate toyos-devicepath (lib/devicepath). It does a bounded, validating walk of UEFI device path bytes. A node shorter than its header, a node past the bytes, no End node, bytes after the End node and multi-instance paths are each refused by name. It decodes the nodes a boot source is made of: ACPI, PCI, USB, SATA, NVMe and HARDDRIVE. It also renders the UEFI text form. The loader's HardDrive decoder moved here, so there is one decoder.

  • ABI. KernelArgs::boot_sources: BootSources { loader, slot } replaces boot_function.

    • Each BootSource holds the path bytes, its length, and the controller.
    • New SYS_BOOT_SOURCES (136) answers the struct whole under Rights::INVENTORY. All three structs are user_safe!.
    • The accessors refuse a field that no loader writes (Unwritten) rather than panicking, so the kernel and a reader both refuse it at their own boundary.
  • Kernel (kernel/src/loaded.rs). At handoff it checks each source. Any of the following panics with the reason, because they are loader bugs:

    • a length or present out of range;
    • a path that does not parse;
    • non-zero bytes outside the fields;
    • a controller with no path.

    The kernel then keeps the sources unchanged and answers them. It interprets no path. Pci::boot_path, inventory byte 14, the inventory marking and the kernel's boot: firmware loaded this boot through line are all removed.

  • Supervisor (toyos_supervisor::boot, pure). It reads the sources once at start and says one line per source, the path in text form plus its controller. It then says either supervisor: \@boot` is PCI bb:dd.f (segment s) (toyos_manifest::device::BOOT_SAID) or why @boot` names nothing.

    • @boot is the controller of the loader's own source only. The slot volume's controller is said but never used for @boot.
    • PciMatch::matches now takes that controller as an argument. With none, @boot matches nothing. Drives::decide and claims::function pass it through.
  • Provenance, not authority. Nothing grants on a path or GUID. Storage still resolves partitions by the GUIDs the loader names (nvme: every image drives NVMe by its class, and a host's disk is left alone #1031), diskserver still refuses duplicate GUIDs, and the slot's signature still covers every byte read. usbd does not yet match the USB nodes of the path to the device it enumerates: nothing needs that today, and the ruling asks for no speculative transports.

  • Test images. Unchanged from round 2: the usbd row is ["pci:0c:03:30/1033:0194", "pci:0c:03:30@boot"]. Two drives entries of one row may still overlap.

  • Judges. spare_xhci and usbd_serves_the_boot_stick read the supervisor's @boot line from the programs' log. usbd_serves_the_boot_stick now also requires that the controller serving the stick is the @boot one, and it prints both source lines.

  • Harness. A boot that times out now prints the 16550's file as well as the console. Without it, a kernel that panics before virtio-console arrives timed out with "nothing at all" (the first run of the path control below).

Checks

Head 618588db7, base 7eefbcb0b, macOS aarch64 host. 17c0367f7 is fbf436e04 rebased over #1028; #1028 touched only toyos-metal, and the tree delta is identical. fbf436e04 is 949d59456 plus the clippy fix in a test.

  • cargo run -- --ci host at fbf436e04: exit 0, "101 step(s), all green". The earlier run at 949d59456 was red only on clippy's redundant_clone in lib/devicepath's test.
  • cargo run -- --build-only at 949d59456: exit 0.
  • QEMU at 949d59456: cargo test --test toyos-build -- the_log_lands_on_the_boot_stick usbd_drives_the_spare nvme_disk_boots a_usb_key_reaches_the_console a_bent_supervisor_is_refused_and_the_other_slot_boots virt_wall_clock_utc: exit 0, 6/6. That covers x86-64 (stick, NVMe and spare profiles) and AArch64 (virt_wall_clock_utc, and the bent-supervisor test on both architectures).
  • Host tests:
    • toyos-devicepath: firmware paths decode and render. Every hostile shape is refused by name: empty, unterminated, truncated header, a zero or 3-byte node, a length past the bytes, a second instance, bytes after End, and an End with data.
    • toyos-abi: the accessors, plus the refusal of path_len 513 and 65535 and of present 2.
    • toyos-supervisor::boot: the loader's controller is @boot. A slot volume's controller is said but not taken. Each hostile source names nothing and says why: an over-long length, an unterminated path, a zero-length node, present 2, and no path.
    • toyos-manifest: @boot matches only the controller given, nothing when given none, and keeps its class.
  • Controls (agents/usbd-boot/r3/controls.sh). Each patch was checked with git apply --check, built, run, and reverted in the same run. They ran at the pre-commit tree of round 3, whose code is this head's apart from the judge, the harness message and the clippy fix.
    • Positive: testcases' usbd row reduced to ["pci:0c:03:30@boot"]. the_log_lands_on_the_boot_stick exits 0. The chain from loader to kernel to syscall to supervisor alone puts usbd on QEMU's stick controller.
    • Negative: the same reduced row, with the supervisor's controller forced to None. Exit 1, STALLED: waiting for usbd to serve the boot stick.
    • Negative: the loader hands a path one byte longer than its End node. nvme_disk_boots exits 1. The 16550 shows PANIC: … kernel/src/loaded.rs … boot: the loader handed the loader source, and bytes follow the End node at byte 76, so the kernel's check fires.
  • Independent oracle for the text form. In the same boot, OVMF's BdsDxe printed PciRoot(0x0)/Pci(0x1,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00) for its boot option, and the loader's rendering of the path it captured begins with the same nodes.

Evidence: https://github.com/ToyOSOrg/evidence/tree/1386018208b1bfb58d9b2b5ad1206302d476c4d7/618588db7

A fix to main, superseded

tests: launch_unsent_stdio names each descriptor's kind (618588db7) repaired main's tests/guest/rust-tests build after #1012. #1024 carries the same fix, and this commit drops at rebase.

Metal

Both runs used testcases at 618588db7, flashed with main's toyos-metal at 7eefbcb. Both verdicts passed.

  • AMD bench, stick in its USB-C port: rows usbd_serves_the_boot_stick, amdvi_remaps_the_stick_controller and amdvi_usbd_drives_its_own_entry.
    • The firmware's path was PciRoot(0x0)/Pci(0x8,0x1)/Pci(0x0,0x4)/USB(0x4,0x0)/HD(1,GPT,…), on PCI 03:00.4.
    • The supervisor reported @boot as 03:00.4, and usbd drove that controller.
    • The deliberate DMA faults hit only the spare controller, 03:00.3.
  • T14: rows usbd_serves_the_boot_stick and usbd_drives_the_type_c_controller.
    • The path was PciRoot(0x0)/Pci(0x14,0x0)/USB(0x0,0x0)/HD(1,GPT,…), on 00:14.0, and @boot was 00:14.0.

Both paths parse within the 512-byte bound.

Not established

  • If firmware loaded the loader off a device with no PCI function on its path, @boot names nothing and a test image drives only QEMU's controller by id. That is explicit, not guessed.

Round 4 (cfe67a96b, base 8d96a8a8b)

  • Every device path the loader reads now goes through one check. DevicePath::path() walks at most DEVICE_PATH_BYTES and holds the result to Path::parse. A failure is refused by name (Unread).
    • boot_partition, boot_disk, bootnext's partition lookup and the boot sources all use it.
    • The unbounded, panicking nodes() is deleted, so the loader/Cargo.toml comment is now true.
  • Fixtures.
    • The T14 fixture in toyos-devicepath and the AMD fixture in toyos_supervisor::boot use the nodes those firmwares named on the 618588d bench runs.
    • Their HARDDRIVE GUID, start and size are synthetic, and each fixture says so. No readback value is committed.
  • Suggestion taken. The SATA arm is dropped, and Node::decode, Known and HEADER are now private. The other two suggestions are declined:
    • the kernel's parse stays as a cheap bug fence;
    • the OnceLock stays.
  • Rebased onto main. The launch_unsent_stdio commit was dropped; spawn: a plain spawn is a helper, and a launch is asked for #1024 carries that fix. One doc-comment conflict, with session: a login is a session under its owner #1035's sessions module, is resolved in lifecycle/src/lib.rs.
  • Checks at cfe67a96b:
    • cargo run -- --ci host: exit 0, 102 steps green.
    • --build-only: exit 0.
    • QEMU the_log_lands_on_the_boot_stick nvme_disk_boots a_bent_supervisor_is_refused_and_the_other_slot_boots virt_wall_clock_utc a_host_disk_beside_the_stick_is_left_alone: exit 0, 5/5 on x86-64 and AArch64.
  • Metal. No rerun. On firmware's well-formed paths the loader reads the same bytes, through the same bounded walk the boot sources used at 618588d. The callers changed only in how they iterate those bytes, plus one refusal line on a malformed path. QEMU's stick and NVMe boots, which go through boot_disk and boot_partition, pass.
  • Evidence.

Rebase onto #1039 and #1040 (9e6beea46, base fc8875cd3)

🤖 Generated with Claude Code

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant