nexoniarz/SchOS
nexoniarz/SchOS
Watch
1
0
Fork
You've already forked SchOS
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: README, plan, guides and the site describe what is built now

Browse source 
README: rewritten around what runs (Linux software, Xorg, apk, Linux's drivers), the honest gaps, measured numbers.
plan/: 1.0.md is the finish line, where each clause of the acceptance test stands, and the register (one failing
clause: a root that survives a reboot); built plans (foundations, hybrid, alpine, xorg) and the decided-against one
(wayland) are gone, their content lives in architecture/; roadmap.md is only what is still open.
guides: building/layout/testing/adding-a-driver (Linux code may be used). history: four entries (ls -lR, TLB
shootdowns, MDIO 0x02460246, netlink MSG_TRUNC). Website: cards, stack, download page, docs index.
Code comments that pointed at deleted plan docs point at the architecture docs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao
This commit is contained in:
Nexoniarz 2026-10-26 08:08:05 +01:00
commit cb3d28e3d6
57 changed files with 685 additions and 2121 deletions
Download patch file Download diff file Expand all files Collapse all files

31
docs/guides/adding-a-driver.md
View file

@ -12,12 +12,20 @@ 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/`.
**BSD: yes. Linux: no.** This is a licence incompatibility rather than a
preference, and it decides the whole strategy — see
[../licensing.md](../licensing.md). BSD-2 and BSD-3 code can be used directly
with a `NOTICE` entry; GPL-2.0-only code can never be, at any distance. Reading
Linux to understand *hardware* is fine and normal; translating a Linux driver
function by function produces a derivative work whatever the identifiers say.
**Three sources, in the order to try them:**
1. **A native driver, written from the specification.** The default, and what every driver in the
kernel is.
2. **Linux's own driver, unmodified, through LDLS** ([ldls.md](../architecture/ldls.md)), when the
device is one Linux supports and SchOS cannot afford to write a driver for — a NIC with a PHY
behind it, a GPU, a Wi-Fi card. It runs in a process, so a crash costs the interface and not the
machine. This is how the laptop's Realtek NIC is driven.
3. **BSD or Linux code taken into the tree.** Licensing no longer forbids either: SchOS is
GPL-2.0-or-later, so GPL-2.0-only code combines with it, and BSD-2/3 code can be used directly with
a `NOTICE` entry — see [../licensing.md](../licensing.md). The reason to prefer 1 and 2 is
maintenance, not law: a driver copied in is a driver that has to be tracked.
Reading another kernel to understand *hardware* is fine and normal.
One caveat about "port it from BSD" as a plan, learned by looking: FreeBSD's
`sys/dev/usb` is roughly 100k lines welded to newbus, devclass, `bus_dma`,
@ -45,7 +53,9 @@ ours.
kernel/drivers/
registry.c
gpu/vga/ gpu/virtio_gpu/
net/e1000/
net/e1000/ net/rtl8139/ net/r8169/
storage/ahci/ storage/nvme/
audio/ac97.c
bus/xhci/
usb/core/ usb/hid/ usb/storage/ usb/hub/
@ -56,11 +66,12 @@ ours.
| 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 |
| `DEVCLASS_DISPLAY` | `struct display_ops` ([display.h](../../include/gfx/display.h)) | none today — Xorg draws through `/dev/fb0` |
| `DEVCLASS_NET` | `struct netdev_ops` ([netdev.h](../../include/dev/netdev.h)) | the TCP/IP stack |
| `DEVCLASS_AUDIO` | `struct audio_ops` | `/dev/dsp` |
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
`gfx_attach_scanout()` ([gfx.h](../../include/gfx/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.