20cc673a41
The TCP/IP stack reached straight into the first driver anyone wrote.
net.c called e1000_present(), the lwIP glue was named netif_e1000.c and
called e1000_transmit(), and include/defs.h declared the driver's
internals to the whole kernel. The second NIC driver would therefore
have arrived with a near-identical copy of the glue file and a patch to
the protocol stack, which is the arrangement include/device.h was
written to prevent -- the e1000 even said so, with `.ops = 0, // no
class vtable yet; there is no net class`.
There is now. A driver publishes a struct netdev_ops -- transmit,
receive, mac, link_up -- and is finished: it never mentions lwIP, and
nothing above it learns its name. The display class was already this
shape; this is the same shape for networking, and the two now read the
same way in kernel/dev/device.c.
What that made possible immediately:
- One netif per bound device instead of one per driver. lwIP's glue is
netif_eth.c, it takes a struct device, and it holds up to NETIF_MAX
interfaces. net.c attaches every network device it finds and starts
DHCP on each, because which interface the network answers on is not
ours to decide.
- /proc/netif lists all of them, one block of fields each, with the
interface name and the driver that claimed it.
- The ARP self-test moved from the e1000 to the class. Nothing in it
was chip-specific, and it is the first thing anyone will want to run
against the next driver. Still `echo n > /proc/sysrq`.
- Private headers live with their driver: e1000.h was in include/,
where exactly one file could use it. The driver build now adds the
driver's own directory to the include path.
The e1000 also drives more than one card. Its probe() refused the second
outright, because there was a single static instance -- so a machine
with two of them drove one and silently ignored the other. Instances are
an array now, and the instance is hung on dev->priv by a new optional
`attached` hook that the bus calls once the device exists. probe() runs
before device_add(), so there was previously nowhere to put it; that is
the whole reason the hook exists rather than a line inside probe.
QEMU gets an explicit NIC on every target (QEMU_NET). The default device
happens to be an e1000 on this machine type today, which is exactly the
sort of thing that stays true until a QEMU release changes it and the
network stops being exercised without anyone noticing.
Verified:
- bootcheck -Net passes, 48 [ok], no failures -- including the moved
self-test and two new checks that /proc/netif names both the
interface and the driver behind it, which together say the stack
went through the class rather than through a driver it was compiled
to know.
- Two NICs attached by hand (-device e1000 twice, second with its own
MAC): eth0 and eth1 both attach, each reports its own MAC in
/proc/netif, and each gets its own DHCP lease. Before this commit
the same machine produced one interface.
- make schfs-check still passes in full.
One trap worth recording: moving a header broke the build for anyone
with stale .d files -- make stopped with "No rule to make target
'include/e1000.h'". CFLAGS gains -MP, which emits a phony target per
header so a moved or deleted one can never wedge the build again.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
155 lines
7.3 KiB
Markdown
155 lines
7.3 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, the console |
|
|
| `DEVCLASS_NET` | `struct netdev_ops` ([netdev.h](../include/netdev.h)) | the TCP/IP stack |
|
|
|
|
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.
|