817d666068
Same disease as the network stack, one subsystem over. kernel/dev/vga.c
was three things wearing one name: the owner of the framebuffer, a
bitmap drawing library, and the text console. Only the first is a
driver, and because they shared a file they shared a prefix -- so
panic.c drew the crash screen with vga_fill_rect, console.c printed with
vga_putc, /dev/fb0 handed out vga_fb_phys, and every one of those files
named a display driver it had no business knowing about.
Split three ways:
- kernel/drivers/gpu/vga/vga_fb.c owns the VBE framebuffer -- the mode
the loader programmed and handed over, the aperture, and the display
class vtable. It is a driver and now lives with the driver that
finds the card on the bus.
- kernel/dev/gfx.c draws: pixels, shapes, glyphs, the cursor, scroll,
the ANSI erase operations. It names no driver. The framebuffer
arrives through gfx_attach_scanout(), so a driver publishes what it
owns and this file draws on it without knowing what it is.
- include/gfx.h is the interface, and says why it is deliberately not
the display class: that one is about frames -- acquire, present,
vblank -- and the crash screen has to work when nothing else does.
main() no longer calls a display driver. platform_register_devices()
takes the framebuffer address and brings up whatever owns it, which is
where driver names belong; kernel/drivers/registry.c is the file whose
entire job is naming every driver in the kernel.
virtio-gpu got the e1000 treatment as well: instances in an array, the
instance hung on dev->priv by an `attached` hook, and every op reading
it rather than a file-static. It refused the second adapter outright
before, which is not hypothetical -- integrated plus discrete is an
ordinary laptop. The VGA driver deliberately has no such hook, and says
so: there is one framebuffer the loader programmed however many
VGA-class controllers the bus turns up, and a second one publishing the
same scanout is the truth rather than a bug.
Private headers moved next to their drivers: include/virtio.h and
include/xhci.h each had exactly one includer. include/ is for headers
the rest of the kernel needs.
Deleted rather than moved: consoleinit() programmed the sixteen ANSI
colours into the VGA DAC and disabled text-mode blink, by writing ports
0x3C0-0x3C9 from the console. The comment three lines above the colour
table already said this does nothing in a 32bpp linear mode -- there is
no palette to index -- so it was both dead and in the wrong file.
Verified, and this is a refactor so the evidence is that nothing moved:
- bootcheck -Fb -Net: 59 [ok], no failures. That covers the console
through every command, /dev/fb0's geometry, writing pixels through
write() and mapping the framebuffer through mmap.
- make crashshot: the crash screen renders exactly as before --
shapes, glyphs, logo and QR code -- which is the whole of gfx.c
exercised at once, in a panic, with the scanout attached by a driver.
- make schcom-test: five pixel assertions from the host oracle still
pass, so the display class and the compositor above it are unmoved.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
161 lines
7.7 KiB
Markdown
161 lines
7.7 KiB
Markdown
# Drivers
|
|
|
|
How hardware gets found, claimed and used, and where drivers that are not part
|
|
of the build will attach.
|
|
|
|
---
|
|
|
|
## 1. The device model
|
|
|
|
There is one list of everything attached, whatever bus found it:
|
|
`include/device.h` and `kernel/dev/device.c`, readable at `/proc/devices`.
|
|
|
|
```
|
|
name bus class driver device
|
|
kbd0 platform input ps2kbd PS/2 keyboard
|
|
mouse0 platform input ps2mouse PS/2 mouse
|
|
uart0 platform other uart8250 16550 serial port
|
|
ide0 platform storage ide ATA disk controller
|
|
vga0 pci display vga display controller
|
|
```
|
|
|
|
Before this there were two registries in `kernel/drivers/registry.c` — an array
|
|
of PCI drivers and an array of USB drivers — with nothing that knew about both.
|
|
That is sufficient for *binding* and useless for the three things wanted next.
|
|
|
|
**Enumeration.** "What is in this machine, and what claimed it" had no answer
|
|
covering a USB disk and a PCI display at once. A device manager is exactly that
|
|
question.
|
|
|
|
**Classes.** A compositor should ask for *the display* and not care whether that
|
|
is the VBE framebuffer or virtio-gpu. Without a class every consumer hardcodes a
|
|
driver, and adding the second driver means editing the consumers — which is how
|
|
a framebuffer address ended up hardcoded in three places here once already.
|
|
|
|
**A boundary for drivers that are not compiled in.** They have to attach
|
|
somewhere that is not an array fixed at link time.
|
|
|
|
Two vocabularies are kept deliberately separate: a device's **bus** is
|
|
provenance (`platform`, `pci`, `usb`), its **class** is capability
|
|
(`display`, `input`, `storage`, `net`, `bus`). A USB disk and a SATA disk are
|
|
both `storage` despite sharing no numbering at all. Where a driver claims a
|
|
device, the driver's opinion wins over the descriptor's: `struct usb_driver` has
|
|
a `devclass` field separate from the USB interface class, because the descriptor
|
|
says what the device *claims* to be and the driver knows what it *made* of it.
|
|
|
|
It is a flat list with a bus tag, **not** a device tree. Nothing yet needs to
|
|
walk a hierarchy, and a tree nobody traverses is just a harder list. Hot-unplug
|
|
would need more; the `in_use` flag is the hook.
|
|
|
|
Platform devices are registered in one place
|
|
(`platform_register_devices()` in `registry.c`) rather than inside each driver's
|
|
init, for the same reason the driver arrays are written out by hand: a list you
|
|
can read beats a list assembled by side effects.
|
|
|
|
---
|
|
|
|
## 2. Where this is going: a hybrid model
|
|
|
|
The intended shape is the NeXTSTEP/macOS one rather than Linux's — a device is
|
|
an object with a class and an ops vtable, and consumers talk to the class.
|
|
|
|
Two things often get bundled together as "loadable drivers" and they are
|
|
separable:
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Loadable modules** | A stable driver ABI, drivers as files loaded at runtime (`.sys`, `.kext`). A linker/loader job on top of the model above. |
|
|
| **Drivers out of kernel** | Drivers as user-space processes (macOS DriverKit, which is why kexts are being retired). An IPC and memory-mapping job; the `AF_UNIX` and shared-memory work it needs already exists. |
|
|
|
|
The second is more in the spirit of the SchAPI direction and is slower and
|
|
larger. Neither is built yet. What exists is the attachment point they both
|
|
need.
|
|
|
|
---
|
|
|
|
## 3. Linux drivers
|
|
|
|
**Decided 2026-08-08.** Linux drivers are not shipped with SchOS and never
|
|
will be. The user may install one on their own machine, through a device
|
|
manager or equivalent, and SchOS will load it.
|
|
|
|
The licensing reasoning matters and is worth stating exactly, because it is
|
|
easy to get wrong in both directions:
|
|
|
|
- **Distribution is what triggers the GPL.** Shipping a GPL-2.0-only driver in
|
|
an Apache-2.0 image is what cannot be done — see [licensing.md](licensing.md)
|
|
§2. A user obtaining a driver themselves and loading it on their own machine
|
|
is their act, not ours, and is not a distribution by us.
|
|
- **Implementing a loader is not copying.** Writing support for a module format
|
|
and a driver ABI from published documentation produces our own work. It is a
|
|
clean-room implementation, and it stays one only if it is written from
|
|
documentation rather than transcribed from Linux source. Reading Linux to
|
|
understand *hardware* is fine; translating its code is not, whatever the
|
|
identifiers say.
|
|
|
|
So the rule for this subsystem is the same as everywhere else in the tree: the
|
|
loader is ours and Apache-2.0, what it loads is the user's business, and nothing
|
|
GPL ever enters an image we build. `RAMDISK_EXCLUDE` and `NOTPORTS` are the
|
|
existing mechanisms for keeping that true mechanically rather than by intention.
|
|
|
|
---
|
|
|
|
## 4. Adding a driver today
|
|
|
|
1. Write `kernel/drivers/<class>/<name>/<name>.c` exporting a
|
|
`struct pci_driver` or `struct usb_driver`. One directory per driver, so a
|
|
driver that grows a register header, a second source file or a firmware blob
|
|
has somewhere to put it:
|
|
|
|
kernel/drivers/
|
|
registry.c
|
|
gpu/vga/ gpu/virtio_gpu/
|
|
net/e1000/
|
|
bus/xhci/
|
|
usb/core/ usb/hid/ usb/storage/ usb/hub/
|
|
|
|
2. Declare it in `kernel/drivers/registry.c` and add it to the array.
|
|
3. Add the object to `KERN_DRIVERS` in the `Makefile`.
|
|
4. Fill in the **class vtable** for what it is, and point `.ops` at it. That is
|
|
the whole of what the rest of the kernel sees:
|
|
|
|
| class | vtable | consumer |
|
|
|---|---|---|
|
|
| `DEVCLASS_DISPLAY` | `struct display_ops` ([display.h](../include/display.h)) | the compositor |
|
|
| `DEVCLASS_NET` | `struct netdev_ops` ([netdev.h](../include/netdev.h)) | the TCP/IP stack |
|
|
|
|
A display driver that owns a linear framebuffer also publishes it with
|
|
`gfx_attach_scanout()` ([gfx.h](../include/gfx.h)). That is what the text
|
|
console and the crash screen draw on, and it is separate from the display
|
|
class on purpose: the class is about *frames* — acquire, present, vblank —
|
|
and the crash screen has to work when nothing else in the system does.
|
|
|
|
A driver that fills these in never mentions its consumer, and its consumer
|
|
never mentions it. Getting this wrong has a characteristic shape: the e1000
|
|
shipped with `.ops = 0` and the network stack called `e1000_transmit()`
|
|
directly, so `kernel/net/` was full of one driver's name and the second NIC
|
|
driver would have had to edit the protocol stack to add itself.
|
|
|
|
Private headers go **next to the driver**, not in `include/`. The build adds
|
|
the driver's own directory to the include path, so `e1000.h` — a register map
|
|
that exactly one file has any use for — lives in `kernel/drivers/net/e1000/`.
|
|
`include/` is for headers the rest of the kernel needs.
|
|
|
|
Registration in the device model is automatic — `pci_bind()` and
|
|
`usb_bind_all()` publish whatever they claim, so a driver cannot forget to. Set
|
|
`devclass` on a USB driver, or the device lands in `other`.
|
|
|
|
A driver that can drive **more than one card at once** keeps its instances in
|
|
an array and implements `.attached`, which the bus calls once the `struct
|
|
device` exists; hang the instance on `dev->priv` there and read it back in
|
|
every op. It cannot be done inside `probe()`, because the device is published
|
|
afterwards. Skipping this is how a driver ends up refusing the second card, as
|
|
the e1000 did until it was asked to drive two.
|
|
|
|
The best source for a new driver is the **specification**, not another kernel:
|
|
xHCI, AHCI, virtio, NVMe and the Intel datasheets are public documents with no
|
|
licence on what you write from them. `kernel/drivers/bus/xhci/xhci.c` came from the spec, and so did
|
|
`net/e1000/` and `gpu/virtio_gpu/`. Where a *table* of constants is genuinely
|
|
faster to transcribe than to retype from a PDF -- device IDs, register offsets --
|
|
taking it from a BSD tree is fine after the licence check, and goes in `NOTICE`.
|
|
That is data; the logic stays ours.
|