A device function is claimed by its arrival, and a drives row has one process per function (lifecycle stage 1.2)

[Japabu]

Stage 1.2 of issues/a-device-function-is-driven-from-its-arrival-to-its-end.md, after #910 (stage 1.1). It follows the design accepted on #910 (6153045378 D1–D5, 6153203682 B2/B3/B8, 6153972713's split).

Problem

A devices row named a PCI function by vendor and device. The kernel resolved that name, and it refused Ambiguous on a machine with two of one card, so the decision about which function a row wants sat in the kernel. A row had one process, started only from [boot] start. One supervisor thread per service parked in SYS_PROCESS_WAIT to see it end. The restart policy was spread across lib/manifest, a waiter thread and the loop.

Change

• Claims by arrival. Each toyos_abi::inventory::Pci record carries an Arrival: the function's number for the boot, never another's (bytes 16..20 of the record). DeviceRequest::Function(arrival) names a function. DeviceRequest::Pci, the pci: spelling in toyos-abi, toyos_pci::claimed and Unclaimable are deleted. SysCap::claim_pci becomes claim_function. endow::pci_function becomes endow::claim(name), which looks a claim up by its entry's spelling.
• The grammar is lib/manifest's (device::Entry, device::PciMatch): pci:CC:SS:PP and pci:CC:SS:PP/VVVV:DDDD, the card spelled by the manifest's own four-digit rule. PciId::parse stays in the ABI only as the kernel's xhci-leave= parameter. Fixed rows (classes, part:, isa:) keep the ABI's spelling. Every matcher carries its class, so overlap is decided from text alone.
• Render refusals, which are build refusals. toyos_manifest::render refuses the following, and the build panics with the error, so every config is held to them by every_config_renders_its_manifest:
  • two entries one device can answer, across rows or within one, naming both rows and entries (RenderError::Overlap). This replaces one_claimant_per_device and keeps its refusal of duplicate class, isa and part: names;
  • an entry that names no device;
  • a drives entry that is no PCI matcher;
  • a drives row with serves, roles or devices, or one listed in [boot] start or in another row's starts.
• toyos-supervisor (system/supervisor/lifecycle, pure, host-tested) holds:
  • restart policy and its budget (restart, moved out of lib/manifest along with Program::supervised);
  • the claims a restart is owed, and the one function a single-process devices matcher names (claims). Two matching functions refuse that row's start, naming both;
  • which functions a drives row has a process on (drives). A refused start, and an end owed no restart, leave the function alone until its inventory record differs from the first one read after. Every start of a function after its first spends that function's budget, and a spent budget gives the function up.
• The supervisor watches every child's Process handle on its loop's poller and on the file worker's wait. A wait without parking reads as running only on WouldBlock; any other refusal on its own handle panics (restart::exited), as the deleted waiter did. The waiter threads, Kept's mutex, the wake pipe and close_when_it_ends are deleted. It reads the inventory at boot and after every end, and performs what Drives::decide answers. A drives process is started with its function's claim under the matcher's spelling, its row's receives, and a log ring of its own.
• vdagent is a drives row (pci:07:80:00/1af4:1043). Its "no virtio-serial function" exit is deleted: no instance starts where nothing matches, and the T14 starts none.
• Images. Every pci: entry gains its class, read from QEMU 11.1.1's configuration space rather than assumed (evidence classes/): NVMe 01:08:02, virtio-net 02:00:00, virtio-sound 04:01:00, virtio-serial 07:80:00, edu 00:ff:00. netstack's I219 and 82574 matchers are 02:00:00 from the PCI Code and ID Assignment class; no image names either.

Decisions to check

• ClaimError::Ambiguous stays, for partitions only. The brief said it goes, but a GPT unique GUID carried twice (gpt::seek) still names two partitions. It has no arrival to choose by, and InvalidArgument is still the honest answer. Only its PCI meaning is deleted.
• D5's serves: serves names only the shared-service role here, so it is refused on a drives row. A drives process reaches its consumer as a client through receives, wired as every row's is. I also refuse roles and devices on such a row: a single-process claim held by one of several processes has no meaning.
• "Until its record changes" compares the whole record, driven included, so a function a competing holder gives back is retried. One consequence: after a failed spawn, the supervisor's own dropped claim is released through ZERO_QUEUE (a live process's close; issues/deferred-release-outlives-its-syscall.md). If the next reading sees that release still pending, the function counts as changed and is retried once more. The budget bounds this, and readings happen only at an end, so nothing spins.
• MAX_CHILDREN (216) is what one poller can watch beside the loop's own tokens. A drives process past it is refused by name.
• The judge reads the inventory. test-runner gains inventory in testcases and virtclaimcase, whose jobs find a function's arrival through tests/guest/rust-tests/src/function.rs.

Tests

• Host: toyos-supervisor 13 tests, among them a_refused_start_is_not_retried_until_its_record_changes, a_function_that_keeps_refusing_is_given_up_on and two_matching_functions_refuse_the_start_naming_both. Grammar, overlap and refusal tests are in toyos-manifest. two_rows_on_one_function_are_a_build_refusal_by_name is in the build crate.
• Guest: a_drives_row_holds_one_process_per_function (new, QEMU x86-64, Profile::HeadlessTwoEdu: the Headless q35 plus two edu; tests/images/drivescase.toml). It needs a guest because the claims by arrival, the two spawns and each holder's own function have no host build. No bench has two identical functions left to a claim, so it has no metal row. What it checks:
  • the kernel hands each edu over exactly once (counted, not a set);
  • two pciholders (tests/guest/pciholder, test-only) each print the function they hold, and the two printed sets are equal;
  • test_rs_drives_judged then reads both as Claimed by pciholder, under distinct pids.
• Existing claim rows rerun green: usbd_drives_the_spare, the_opening_exchange_with_qemus_agent_completes (vdagent as a drives process), bar_map_again, lent_device_memory_refused, iommu_virtio_platform (its supervisor lines now spell the matcher) and virt_claim_lpi (aarch64).

check	command	revision	target	exit
host	cargo run -- --ci host	14a707b1b, and 28360a6e5 after review round 1	host	0, 83 steps, both
guest, the drives arm after review round 1	cargo test --test toyos-build -- --nocapture a_drives_row_holds_one_process_per_function	28360a6e5	QEMU 11.1.1	0
image	cargo run -- --build-only	14a707b1b	build	0
guest, 7 arms	cargo test --test toyos-build -- --nocapture a_drives_row_holds_one_process_per_function usbd_drives_the_spare the_opening_exchange_with_qemus_agent_completes bar_map_again lent_device_memory_refused iommu_virtio_platform virt_claim_lpi	14a707b1b	QEMU 11.1.1	0, 7 passed
mutation: refusal retried every reading	toyos-supervisor tests	14a707b1b+patch	host	101, livelock red at round 0
mutation: ambiguous matcher goes on	toyos-supervisor tests	14a707b1b+patch	host	101
mutation: PCI matchers never overlap	toyos-manifest tests	14a707b1b+patch	host	101, grammar and render tests
mutation: one process per row	the drives guest arm	14a707b1b+patch	QEMU	1, one holder, stalled
T14	usbd_drives_the_type_c_controller (testcases-xhci-leave, its two jobs and assertions unchanged), run by the orchestrator	c3f4e070f	T14	judge 0, PASS, 1 boot
AMD bench	amdvi_translates_the_stick_controller (testcases boot), run by the orchestrator	c3f4e070f	AMD bench	judge 0, PASS, 1 boot

c3f4e070f and 9029901b5 change only issues/ after 14a707b1b. Review round 1 (28360a6e5) changes the manifest's card parse, exit_of's classification, a doc, a render refusal and the drives arm's judge: the host run and the drives arm were rerun; the other six QEMU rows and the benches were not, since none of them reads those paths (exit_of's new arm is an error path, held by the crate's host tests). Every check before the merge of main, at 26609b4cd, was rerun after it, because #916 changed pcidev.

The whole-change control cannot run as a test: the base has no drives field, so the guest arm's image does not build there. The informative controls are the four mutations above.

Evidence: https://github.com/ToyOSOrg/evidence/tree/d05131156f8d780c6d6a231d2c5aacb69c9bbb01/lifecycle-s1/stage-1-2 (the metal runs, masked, under metal-runs/; review round 1 under review-1/).

Records

• The track records stage 1.2 as done. The three folded tracks are updated: the child's-end track's stage 1 is done, the supervisor track's stage 2 starts from toyos-supervisor, and the kernel track's step 10 names usbd as this track's stage 4 drives row.
• Three records this change made stale are corrected minimally (9029901b5):
  • issues/diskserver-claims-qemus-nvme-by-its-pci-id.md: its row's spelling, who matches it, the two-controller refusal and the grammar its exit names. Its class-only rows and its use-intel-id boot are still owed.
  • issues/a-claims-own-refusals-are-read-by-nothing.md: ClaimError::Ambiguous is a partition GUID carried twice.
  • issues/the-supervisors-claim-of-a-pci-function-the-t14-lacks-holds-preemption-off-for-3-8-ms.md: the 3.8 ms stays as measured, with a note that the path no longer exists in that form, that one unmeasured SYS_DEVICE_INVENTORY read replaced it, and that its exit reads a claim no boot now makes (8d9503f47). It is not re-measured.

Declined

• Review S2: usbd_spare and end_returns_claims still endow and print the old pci:VVVV:DDDD form. usbd looks its claim up by the dev:pci: prefix, so either spelling works, and changing it would change usbd_drives_the_spare's and the T14 row's asserted lines. Stage 4's drives row for usbd is where the matcher spelling pci:0c:03:30/… becomes its label.

Cost

• Production: toyos-supervisor is about 250 lines and its tests about 220. The manifest grammar is about 200 lines, under half of them tests. The supervisor is +328/−271. Kernel, ABI and SDK are net −78 (+128/−206), as the review measured.
• Tests: one new 40-line program crate (pciholder), one 50-line judge job, one image and one profile.

Risks

• Every boot now reads the inventory whenever a row with a PCI matcher starts and after every end. That is one syscall each, and no change on machines that have no such rows.

🤖 Generated with Claude Code

https://claude.ai/code/session_016UzbDnM9m6nQWhbjGi6Lv1

[Japabu]

Pushed since the draft opened:

• 9029901b5 — issues: three records this change made stale (diskserver NVMe row, ClaimError::Ambiguous, the 3.8 ms claim) now say what is true after it.

The metal rows passed (T14 usbd_drives_the_type_c_controller, AMD bench amdvi_translates_the_stick_controller, both at c3f4e070f). Evidence, masked: https://github.com/ToyOSOrg/evidence/tree/bc94dee98098ffa03a05f8a528443f63851dc2ac/lifecycle-s1/stage-1-2/metal-runs

[Japabu]

Review of #926 at c3f4e070f (lifecycle stage 1.2, instances per function)

Architecture

The ownership is right. The kernel now owns only what it must: a boot-stable number per function (Arrival, the function's index in FUNCTIONS plus one) and an exclusive claim on that number. Which function a row means is decided in userland. lib/manifest owns the matcher text and the overlap refusal, the pure toyos-supervisor owns the decisions, and the supervisor performs them.

• Replacing the waiter threads, Kept's mutex and the wake pipe with level-triggered watches on each child's Process handle removes a whole concurrency layer. Rc<RefCell<…>> now makes it a compile error to share those ports with the worker thread.
• one_claimant_per_device and names_only_real_capabilities' device half fold into one render refusal that compares parsed values, not strings. That is stricter than the old check: two spellings of one part: GUID now collide.
• Net size: +1684/−721.
  • Production: about +250 in toyos-supervisor, 193 in the grammar with 91 of those tests, and supervisor main.rs +328/−271.
  • Kernel, ABI and SDK: +128/−206 measured, which is −78. The body says −47.
  • Tests: +257/−42.

Brief item 1:

• Arrival cannot be reused. publish asserts it runs once, FUNCTIONS is never rewritten, a release does not touch it, and nothing in stage 1 re-enumerates.
• DeviceRequest::Pci, toyos_pci::claimed and Unclaimable are deleted with no residue outside issues/.
• "Nothing of the grammar in toyos-abi" holds only partly. See B1.

Findings

BLOCKER

B1. lib/manifest/src/device.rs:62 with sdk/abi/src/syscall.rs:1366-1405: the card half of the matcher grammar is still toyos-abi's.

• PciMatch::parse hands VVVV:DDDD to toyos_abi::syscall::PciId::parse. The lowercase-four-digit spelling rule (hex16) and its test a_pci_id_is_four_lowercase_hex_digits_each_and_nothing_else (:2751) still live in the ABI.
• A process's end is published only after its own releases have run (device lifecycle stage 1a) #910's B8 ruling says the pci: grammar "lives in lib/manifest, never in toyos-abi". As it stands, changing the kernel boot parameter xhci-leave='s spelling changes the manifest grammar.
• PciId::parse's doc (:1366-1367) is also now false: "one spelling per function, so that comparing the strings compares the functions". The PciId doc just above it says two cards share an id and an id "names no single function".
• No PciId crosses a syscall any more. Its remaining ABI users are the kernel's own actuator.rs, pcidev and probe.
• Cheapest fix: give lib/manifest its own hex16 beside hex8 (about 10 lines) and move the spelling test there. Keep PciId::parse only for xhci-leave=, or move it into kernel/src/actuator.rs, and correct its doc.

B2. system/supervisor/src/main.rs:2454-2456: exit_of turns every process_wait_nonblock error into "still running".

• The handle is the supervisor's own Child, so any answer other than WouldBlock is an invariant violation. The deleted close_when_it_ends panicked on exactly this ("a service's own process handle refused its wait").
• Failure scenario: a watch on that handle is answered with an error. Poller::wait still delivers TOKEN_ENDED, ended() finds no exit, and the loop re-watches and wakes again. The supervisor spins at full CPU forever and says nothing.
• Fix: Err(SyscallError::WouldBlock) => None, and panic with the error on anything else.

B3. sdk/abi/src/syscall.rs:1536-1541: a false comment in a paragraph this PR rewrote.

• It says four places read the devices spelling, naming "the build system's gate … the kernel's claim".
• The kernel reads a class and two selector words, never a spelling.
• The build's gate is now toyos_manifest::render through Entry::parse, not a separate reader.
• Fix: shorten it to what is true, or delete the sentence.

Records (brief item 5): sentences now false

The track marks 1.2 done truthfully. The three folded tracks are updated accurately:

• the child's-end track's stage 1;
• the supervisor track's stage 2, "partly done";
• the kernel track's step 10, usbd as stage 4.

In the three issues the body names, these sentences are false at this head:

• issues/diskserver-claims-qemus-nvme-by-its-pci-id.md
  • L9-10: "Both shipped boot configs give diskserver one device, pci:1b36:0010". It is now pci:01:08:02/1b36:0010.
  • L11-12: "A claim matches the id exactly (pcidev::claim, kernel/src/pcidev/mod.rs)". The kernel claims by arrival. The supervisor's matcher (toyos_manifest::device::PciMatch::matches, resolved in toyos_supervisor::claims::function) matches class and id.
  • L37-38: "a machine with two NVMe controllers matches twice, which pcidev::claim refuses as Ambiguous today". The supervisor now refuses diskserver's start, naming both functions, and diskserver's ports close that boot.
  • L45-46, the exit: "names a PCI function by class code, which toyos_abi::syscall::DeviceRequest::parse takes and refuses malformed". The parser is now PciMatch::parse in lib/manifest, and the class-only form pci:01:08:02 already exists. What remains owed is the shipped rows going class-only and the use-intel-id=on boot.
• issues/a-claims-own-refusals-are-read-by-nothing.md
  • L14: "ClaimError::Ambiguous, a config naming a device this machine has two of". It is now only a partition unique GUID carried twice.
• issues/the-supervisors-claim-of-a-pci-function-the-t14-lacks-holds-preemption-off-for-3-8-ms.md
  • L15-17: "By reading, the claim reads the vendor ID of each of the 24 functions the kernel enumerated". pcidev::claim now looks the arrival up among cached identities and reads no config space to find it.
  • L23: the quoted line supervisor: diskserver: no pci:1b36:0010 on this machine is now no pci:01:08:02/1b36:0010 on this machine, and it is decided from the inventory without any SYS_DEVICE_CLAIM.
  • L46-49, the exit, measures "that claim" on the T14, which no longer runs at boot. The issue's present-tense subject is gone.
  • The measurements are history and stay true as history. What replaces the claim is one SYS_DEVICE_INVENTORY read, which has not been measured. The issue should say that, or close on a T14 reading.

Confirmed (brief items 2, 3, 4 and 6)

• Grammar and build refusal (lib/manifest/src/lib.rs:492):
  • Two entries one device can answer are refused across rows and within one, naming both rows and entries (RenderError::Overlap).
  • Duplicate class, isa and part: names are still refused, now by parsed value.
  • The build panics with the error, and two_rows_on_one_function_are_a_build_refusal_by_name holds that. one_claimant_per_device has no residue.
  • Hostile manifest text is refused in table tests: wrong field counts, uppercase, a missing class, a trailing /, +1, a bare prefix and multibyte bytes (through the length and ASCII check). The manifest is signed-image input, so table tests suffice and fuzzing is not needed.
• Pure crate:
  • Drives::decide treats a refused start, and an end owed nothing, as held until the record differs from the first reading after it. Every start after the first spends that arrival's Budget, and a spent budget is final.
  • The livelock law is red under the refused-retries mutation (round 0). The budget is covered by a_function_that_keeps_refusing_is_given_up_on and the_budget_is_restarts_inside_the_window.
  • The runtime is a thin consumer. ended() only runs after readiness, so nothing polls.
  • No thread is left: Worker is the existing file worker.
  • vdagent is a drives row. Its exit for a missing function is gone and became an expect on an endowment the supervisor guarantees.
  • A single-process devices matcher that names two functions refuses the start, naming both.
• Tests:
  • The new arm is a real two-instance check. The log at 14a707b1b, serial 3, shows both edu handed over, two pciholders each naming its own function, and drives_judged reading both Claimed under pids 4 and 5.
  • All four mutations are real: the patches are in evidence, each is red (101, 101, 101, and a QEMU stall with one holder), and each was reverted.
  • The whole-change control is honestly stated as impossible: the base parses no drives.
  • c3f4e070f differs from 14a707b1b only in four issues/ files (verified), so the 7 QEMU rows still cover the code.
  • The existing service-end path ran in that evidence: netstack exits 0 on the no-unit boot (serial 2) and the boot stays green. The restart path has no guest reader, as the child's-end track records. Its decision is host-tested.
• Host: cargo run -- --ci host at c3f4e070f in my worktree exited 0, "Host: 83 step(s), all green".

SUGGESTION

• S1. tests/toyos.rs:3917: handed is a set, so "the kernel hands each edu over once" is not checked. A function handed over twice, for example a holder restarted, would pass. Count the lines, or narrow the body's wording.
• S2. tests/guest/rust-tests/src/bin/usbd_spare.rs:78-80, end_returns_claims.rs:45-47, tests/images/testcases.toml:65: these spell the deleted pci:VVVV:DDDD form. usbd_spare uses it as the endowment label. The matcher spelling pci:0c:03:30/1b36:000d is what stage 4's drives row will endow.
• S3. claims_apart: it refuses a drives row in [boot] start, but not one named in another row's starts. A launch of such a row gets no claim, and vdagent's expect then panics. One more arm closes that.
• S4. Body corrections (the orchestrator's):
  • Kernel, ABI and SDK are −78, not −47.
  • toyos-supervisor is about 250 production lines and 220 test lines.

Verdict

SEND BACK: three small blockers (B1, B2, B3), and the record corrections above, which the orchestrator has said land in this PR. Once those are resolved this is LAND, pending the T14 and AMD bench rows. None of the three blockers changes behavior any test reads, so fixing them needs host checks only, not another guest run.

[Japabu]

Review round 1 (6173329461) answered at 28360a6e5, with 8d9503f47 after it (one issue file):

• B1: PciMatch spells its card with lib/manifest's own four-lowercase-digit rule; the spelling test moved there. PciId::parse stays in the ABI as the xhci-leave= parameter alone, and its doc says so.
• B2: exit_of goes through toyos_supervisor::restart::exited: WouldBlock is running, an exit code is the end, anything else panics. Held by two host tests in the crate (the panic arm by should_panic).
• B3: DeviceRequest's doc says only what reads its spelling.
• Taken: S1 (the drives arm counts hand-overs and holder lines as lists), S3 (a drives row named in a starts is a render refusal, with a test arm). Declined: S2, reason in the body.
• Records: your stale-sentence list matches 9029901b5; 8d9503f47 adds to the 3.8 ms issue what replaced the claim (one unmeasured inventory read) and that its exit reads a claim no boot makes.
• Body: kernel/ABI/SDK is −78.

Rerun: cargo run -- --ci host at 28360a6e5, 83 steps green; the drives arm at 28360a6e5, passed. Not rerun: the other QEMU rows and the benches (no path they read changed). Evidence: https://github.com/ToyOSOrg/evidence/tree/d05131156f8d780c6d6a231d2c5aacb69c9bbb01/lifecycle-s1/stage-1-2/review-1