57aff40228
docs/ was ten files where a plan, a description, a guide and a bug report all
sat next to each other. It is now architecture/ (what SchOS is), plan/ (what it
will be), guides/ (how to work on it) and history/ (why it is like this), with
an index that states the one rule holding it together: when something is
finished it moves from plan/ to architecture/ and is rewritten as a description
of the thing rather than a record of building it.
A ticked checkbox says the work happened. It does not say what the work
*produced*, and six months later the checkbox is all that is left. The network
stack proved the point: finished, verified end to end, and for a month the only
description of it anywhere was a checkbox four levels of indentation deep.
So roadmap.md went from 534 lines to 181 -- nothing deleted, the done work
graduated. Seven subsystems that were finished and undescribed now have
descriptions: boot, kernel, syscalls, filesystem, networking, graphics, usb,
init. Every one ends with "What it does not do", which is the section that pays;
a document listing only strengths is marketing, and the reader who needs it most
is the one about to trip over a limitation nobody wrote down.
schfs.md still opened with "phases 1 through 3 1/2 are done, phase 4 is next"
long after all five had landed. It is a description now, with the phase record
and the hard-won bugs moved to history/.
Three corrections found on the way, all load-bearing:
* projects/schcom/README.md claimed SCM_RIGHTS was done. There is no
sendmsg/recvmsg in the kernel at all, and an entire GUI plan rested on it.
* The root README said "No TCP/IP" months after the stack landed.
* history/kernel.md sec.7 was marked "in progress" on a problem that process
groups solved.
Also adds plan/1.0.md, which draws a finish line so the open list stops being
infinite, and marks schwm/ and schde/ superseded: in Wayland the compositor is
the window manager, so that split dissolves rather than being abandoned.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
4.7 KiB
| name | description | metadata | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| schunix-device-model | The bus-agnostic device model behind /proc/devices, and the settled decision on how Linux drivers may be used. |
|
Built 2026-08-08. include/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/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 firstacquire(), 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.