diff --git a/CLAUDE.md b/CLAUDE.md index dc5af9644b..2c30978647 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,15 +26,17 @@ Read the code for current behavior. `Cargo.toml` accounts for packages; `images/ The supervisor constructs process namespaces and endowments. The kernel enforces object authority; each userland protocol validates its own inputs and grants. The target is per-program filesystem views; inspect the storage track and code for the remaining shared kernel paths. +ToyOS trusts only what it cannot avoid trusting: the CPU and chipset vendor with its signed microcode, the platform firmware (UEFI, AML, SMM), which already controls the whole machine, and the signed image with its pinned toolchain and crates. Everything else is isolated: programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU. The single exception is a privilege beyond a normal device claim, such as a reset line, DMA without an IOMMU or a firmware register window: it is granted only in the signed image's `system.toml`, to a program that image ships, and a package installed later never gets one, whoever signed it. Inside the trusted base a check is a bug fence, kept where it is cheap and catches our own mistakes, such as a write landing in RAM, the IOMMU, the interrupt controllers or another driver's device; it never withholds a feature for want of a vendor document. + The loader owns every UEFI call, before ExitBootServices. CPU control registers come from one declaration, applied and asserted on every CPU. Input translation belongs in userland, per surface. The kernel's logging responsibility is its record ring and console; logkeeper owns the log file. POSIX compatibility belongs in `sdk/libc`, never in the kernel's native interface. Read the relevant subtree's `CLAUDE.md`: `kernel/`, `system/`, `tests/`, `build/`, `apps/` or `sdk/window/`. Module comments should state only contracts needed to use the code. Issue format lives in `issues/README.md`; agent responsibilities live in `.claude/agents/`. ## Research and dependencies -Choose designs on their merits for modern hardware. Use vendor documentation, published specifications and research. Measurements test assumptions and expose regressions; a missing gain on one bench does not alone reject a sound general design. Label proposals and inferences honestly. Creative architectural exploration may precede measurement; uncertain implementation assumptions must be investigated before relying on them. +Choose designs on their merits for modern hardware. Use vendor documentation, published specifications and research. Take a fact first from the vendor's document or the governing published specification, then from the vendor's own code under any licence, including its engineers' code for another OS, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Measurements test assumptions and expose regressions; a missing gain on one bench does not alone reject a sound general design. Label proposals and inferences honestly. Creative architectural exploration may precede measurement; uncertain implementation assumptions must be investigated before relying on them. -Read another implementation's source only clean-room: one agent derives facts and keeps source provenance in its evidence; another implements from those facts without seeing the source. The derived specification goes in the implementation brief, not the repository. Editing an upstream fork is governed by the implementer's fork rules. No upstream pull request is sent for now. +Read another implementation's code, whoever wrote it, only clean-room: one agent derives facts and keeps the provenance of each in its evidence, never in the repository; another implements from those facts without seeing the code. The derived specification goes in the implementation brief, not the repository. A vendor's document is still cited at the site. Editing an upstream fork is governed by the implementer's fork rules. No upstream pull request is sent for now. Use general, widely used crates as published when they are the cleanest solution. Write ToyOS-specific functionality ourselves, including drivers; minimize kernel dependencies and keep libc out of the kernel. A security boundary may justify our own well-tested crate. A fork carries upstream-quality source changes and goes when upstream supplies them; packaging alone uses unmodified source pinned by hash. diff --git a/issues/toyos-supports-thunderbolt-and-usb4.md b/issues/toyos-supports-thunderbolt-and-usb4.md new file mode 100644 index 0000000000..2e972d1df4 --- /dev/null +++ b/issues/toyos-supports-thunderbolt-and-usb4.md @@ -0,0 +1,25 @@ +--- +status: open +kind: track +opened: 2026-10-13 +--- + +# ToyOS supports Thunderbolt and USB4, PCIe tunnelled through them included + +The owner wants it (2026-10-13), and nothing of it is designed yet. Until a +design is put to him and ruled, "Refuse external, record reflash" (owner, +2026-10-04) holds: a userland driver's claim of a function below an external +port is refused by name (`issues/the-iommu-refuses-nothing-yet.md`, +`issues/a-driver-that-reflashes-its-device-escapes-its-isolation.md`). + +**Constraint**: root `CLAUDE.md`, the trust model under Architecture. + +Owner: the orchestrator. + +**Exit**: a metal row on a bench machine with a Thunderbolt or USB4 port reads, +with a device plugged into that port: the device is enumerated and driven; a +PCIe function tunnelled through it is claimed by a userland driver and its DMA +into its grants completes; and that function aimed at memory no grant maps is a +`DMA FAULT` record, the machine still running, as the row's negative control. +The owner's ruling on the design retires the external-port refusal and its row +in `issues/the-iommu-refuses-nothing-yet.md`'s exit.