a1c965da1e
Sixty-five headers sat side by side in include/, so `#include "irq.h"` said nothing about where irq.h was or what it belonged to, and errno.h, stat.h and fcntl.h at the top shadowed the system's for any host tool built with -I./include. They are in folders now -- arch/ core/ fs/ dev/ gfx/ net/ uapi/ (and ldls/ for the Linux driver layer) -- and every include names the folder, as Linux's do: "core/proc.h". Done mechanically and checked the hard way: the kernel built from this tree disassembles identically to the one built from the tree before it. The full image boots, and userland is the same set of programs. Paths in docs and comments follow; docs/guides/layout.md has a table of what is where, and tools/fix-includes.py rewrites old-style includes from the folders in the tree, for code written before this. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1giNvrHTrPMPw7V6x1kQ4
92 lines
4.7 KiB
Markdown
92 lines
4.7 KiB
Markdown
---
|
|
name: schunix-device-model
|
|
description: "The bus-agnostic device model behind /proc/devices, and the settled decision on how Linux drivers may be used."
|
|
metadata:
|
|
node_type: memory
|
|
type: project
|
|
originSessionId: 9d8a2aef-bcf0-47a0-96c6-f706efab4a95
|
|
modified: 2026-08-08T18:05:13.551Z
|
|
---
|
|
|
|
Built 2026-08-08. `include/dev/device.h` + `kernel/dev/device.c`, readable at
|
|
`/proc/devices`. Written up in `docs/architecture/devices.md`. Supersedes the two separate
|
|
arrays in `kernel/drivers/registry.c` as the answer to "what is attached".
|
|
|
|
**Bus is provenance, class is capability** — keep them separate. `bus` is
|
|
`platform`/`pci`/`usb`; `class` is `display`/`input`/`storage`/`net`/`bus`. A USB
|
|
disk and a SATA disk are both `storage`. `device_find_class()` is how a consumer
|
|
asks for "the display" without naming a driver, which is what stops the next
|
|
display driver requiring edits to every consumer.
|
|
|
|
Where a driver claims a device, **the driver's opinion beats the descriptor's**:
|
|
`struct usb_driver` gained a `devclass` field distinct from the USB interface
|
|
class, because the descriptor says what the device claims to be and the driver
|
|
knows what it made of it. A USB driver that forgets to set it lands in `other`.
|
|
|
|
Registration is automatic in `pci_bind()` and `usb_bind_all()` so a driver
|
|
cannot forget; platform devices are registered by hand in
|
|
`platform_register_devices()` in registry.c, in one readable block, matching
|
|
that file's existing "a list you can read beats a list assembled by side
|
|
effects" reasoning.
|
|
|
|
Flat list with a bus tag, **not a device tree** — nothing walks a hierarchy yet.
|
|
No lock: everything is added during single-threaded boot. **USB hotplug would
|
|
break both assumptions** and needs a spinlock plus a reader lock in procfs.
|
|
|
|
## The display class
|
|
|
|
`include/gfx/display.h` + ops in `kernel/dev/vga.c`, published on the device by
|
|
`vga_pci_driver.ops`. `struct pci_driver` gained an `ops` field for this —
|
|
**it has to live on the driver, not be set inside probe()**, because
|
|
`pci_bind()` registers the device *after* probe returns.
|
|
|
|
Ops: `mode`, `acquire`, `present(x,y,w,h)`, `wait_vblank`. The wrappers in
|
|
device.c null-check every op so consumers are not each written around a
|
|
maybe-absent vtable.
|
|
|
|
- **Back buffer comes from `dma_alloc()`, which is the wrong pool** and is used
|
|
because it is the only *physically contiguous* allocator in the kernel —
|
|
kalloc hands out single pages. 1.9 MB of a 4 MB arena meant for device rings.
|
|
Allocated lazily on first `acquire()`, never at boot. The real fix travels
|
|
with the E820 work ([[schunix-smp-and-memory-bugs]]).
|
|
- **vblank is the 1987 VGA port 0x3DA bit 3**, not VBE — VBE's protected-mode
|
|
interface for this is optional and usually absent. Two loops (wait for the
|
|
current retrace to *end*, then for the next to begin), or you return
|
|
immediately having just missed one. Both loops are bounded so hardware that
|
|
never reports retrace cannot hang a caller holding the console lock.
|
|
|
|
`echo d > /proc/sysrq` runs `display_selftest()`; `tools/dispshot.ps1`
|
|
photographs it to `build/dispshot.ppm` — it was derived from crashshot.ps1 and
|
|
originally kept its output path, so the two silently overwrote each other and
|
|
`crashqr.py` then failed on a capture that was not a crash screen. The pattern is designed to fail visibly: quadrants slant on a
|
|
stride error, change colour on a bpp error, and the 1px inset frame clips on an
|
|
off-by-one in the present rectangle. Verified 2026-08-08.
|
|
|
|
The console still writes *directly* to the framebuffer; the two paths coexist
|
|
deliberately. Routing text through the back buffer would mean presenting per
|
|
character.
|
|
|
|
## Linux drivers — settled 2026-08-08
|
|
|
|
Nexoniarz's decision, and the reasoning is correct: **not shipped, ever**; the
|
|
user installs one themselves through a device manager and Schunix loads it.
|
|
|
|
- *Distribution* is what triggers the GPL. A user obtaining and loading a driver
|
|
on their own machine is their act, not ours.
|
|
- Implementing a *loader* from published documentation is clean-room and fine —
|
|
it stays clean-room only if written from docs, not transcribed from Linux
|
|
source. See [[schunix-licensing]].
|
|
|
|
Also worth keeping separate when this resumes: "loadable modules" (a stable ABI
|
|
plus a linker/loader, on top of this model) and "drivers out of kernel"
|
|
(user-space processes, DriverKit-style — needs IPC and mmap, both of which
|
|
already exist). They get bundled together in conversation and are different
|
|
projects.
|
|
|
|
## Adding /proc files
|
|
|
|
Three places, all needed: a `PROC_*` id and a case in `proc_gen_global()` in
|
|
`kernel/dev/procfs.c`, and a row in the `globals[]` table in
|
|
`kernel/fs/procfs.c`. Miss the third and the file exists but cannot be opened by
|
|
name. `sb_pad()` exists there now for column layout — cprintf has no width
|
|
specifier.
|