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

26
docs/architecture/README.md
View file

@ -16,11 +16,10 @@ its distribution.
| Kernel | **SchIFT** | Multi-core x86-64 kernel with a modular VFS |
| Filesystem | **SchFS** | Transactional, copy-on-write, the root filesystem |
| API | **SchAPI** | The native programming interface — *designed, not built* |
| Compositor | **Schcom** | Owns the display; v0 runs |
| Packages | **apk** | Alpine's package manager manages the root; SchOS itself is the package `schos-base` |
Twelve virtual terminals sit under all of it -- `/dev/tty1`..`tty12`, Ctrl+Alt+F1..F12
or `chvt N` --
each with its own screen, line discipline and foreground process group. See
or `chvt N` -- each with its own screen, line discipline and foreground process group. See
[terminals.md](terminals.md).
---
@ -29,9 +28,11 @@ each with its own screen, line discipline and foreground process group. See
```
┌─────────────────────────────────────────────────┐
│ toybox kilo mksh zsh musl first-party cmd/ │ userland
│ Xorg + Window Maker · Alpine's packages (apk) │ desktop, userland
│ toybox mksh musl first-party cmd/ │
├─────────────────────────────────────────────────┤
│ vgpud — a driver that is an ordinary process │
│ vgpud, ldlsd — drivers that are ordinary │
│ processes (and Linux's r8169 inside ldlsd) │
├─────────────────────────────────────────────────┤
│ schinit — PID 1, job manifests, supervision │
├─────────────────────────────────────────────────┤
@ -45,7 +46,8 @@ each with its own screen, line discipline and foreground process group. See
├─────────────────────────────────────────────────┤
│ /dev/pci — MMIO, DMA and IRQs to a process │ ← the eviction seam
├─────────────────────────────────────────────────┤
│ drivers: xHCI e1000 virtio-gpu VBE IDE PS/2│
│ drivers: xHCI AHCI NVMe e1000 8139 r8169 AC97 │
│ virtio-gpu VBE IDE PS/2 I2C-HID │
├─────────────────────────────────────────────────┤
│ scheduler │ paging │ traps │ IRQ │ SMP │ DMA │ SchIFT core
└─────────────────────────────────────────────────┘
@ -59,7 +61,8 @@ never names its consumer and a consumer never names a driver. And at
**`/dev/pci`**, a driver stops having to be in the kernel at all: a process is
handed a device's registers, DMA memory and interrupts, and the in-kernel driver
that held it releases it cleanly. `vgpud` is the virtio-gpu driver living out
there today. See [../plan/hybrid.md](../plan/hybrid.md).
there today, and `ldlsd` runs Linux's own drivers the same way. See
[devices.md](devices.md) and [ldls.md](ldls.md).
---
@ -91,9 +94,12 @@ Read in this order if you are new:
| [fat.md](fat.md) | FAT12/16/32 with long names: USB sticks, SD cards, the ESP. |
| [devices.md](devices.md) | Buses, classes, binding, and the vtables consumers talk to. |
| [usb.md](usb.md) | xHCI, the USB core, and the three class drivers. |
| [graphics.md](graphics.md) | Framebuffer, text rendering, the console, and PSOGM. |
| [terminals.md](terminals.md) | The six virtual terminals, and the chord that switches them. |
| [networking.md](networking.md) | NIC drivers, lwIP, and both socket families. |
| [graphics.md](graphics.md) | Framebuffer, `/dev/fb0`, text rendering, the console, PSOGM and GMMOS. |
| [desktop.md](desktop.md) | Xorg on the framebuffer, Window Maker, and what they stand on. |
| [packages.md](packages.md) | The apk root: Alpine's packages, and SchOS as one of them. |
| [scff.md](scff.md) | The compressed image the live root ships as. |
| [terminals.md](terminals.md) | The twelve virtual terminals, ptys, and handing one to a display server. |
| [networking.md](networking.md) | NIC drivers, lwIP, and the socket families. |
| [audio.md](audio.md) | `/dev/dsp`, AudioEngine, and the AC'97 driver under it. |
| [init.md](init.md) | `schinit`, PID 1 as a role, and the job manifests. |
| [debugging.md](debugging.md) | Symbols, a log that outlives the kernel, and asking the kernel a question. |

2
docs/architecture/boot.md
View file

@ -44,7 +44,7 @@ because there are none.** Everything the jump needs is computed before.
### The hand-off block
One page of low memory at `0x30000`, defined once in
[`include/arch/schboot.h`](../../include/schboot.h) and included by both the loader
[`include/arch/schboot.h`](../../include/arch/schboot.h) and included by both the loader
and `entry.S` so the two cannot disagree.
| Offset | What |

2
docs/architecture/devices.md
View file

@ -191,7 +191,7 @@ bitmap, and loses them when it releases or exits. Granting it is not optional
a driver's `outl` is an instruction compiled into it, not a call anything can
intercept — and granting it *coarsely* is not acceptable, because `IOPL=3` is
one flag that hands over the interrupt controller and the disk along with the
NIC. See [../../include/ioperm.h](../../include/ioperm.h).
NIC. See [../../include/arch/ioperm.h](../../include/arch/ioperm.h).
### Handing a device over

6
docs/architecture/graphics.md
View file

@ -11,7 +11,7 @@ layer, the crash screen — and `/dev/fb0`, which is how Xorg reaches the screen
This distinction causes confusion every time somebody meets it, so it is the
first thing here.
| | [`gfx.h`](../../include/gfx.h) | [`display.h`](../../include/display.h) |
| | [`gfx.h`](../../include/gfx/gfx.h) | [`display.h`](../../include/gfx/display.h) |
|---|---|---|
| **What** | The kernel's own drawing surface | A frame interface for a display server |
| **About** | Pixels and text | *Frames* |
@ -281,7 +281,7 @@ beyond that.
## Text
[`include/gfx/text.h`](../../include/text.h) + `kernel/dev/text.c`.
[`include/gfx/text.h`](../../include/gfx/text.h) + `kernel/dev/text.c`.
**The font was never the problem — the character-cell grid was.** The console
draws text by indexing `font_data[256][16]` and stepping the cursor eight
@ -609,7 +609,7 @@ is the report and the keyboards the laptops have; the xHCI path is the least exe
## One palette
[`include/gfx/theme.h`](../../include/theme.h). There were three unrelated designs
[`include/gfx/theme.h`](../../include/gfx/theme.h). There were three unrelated designs
and the seams showed: the splash was deep purple with gold text deliberately
matching the *panic* screen, the console was cream with near-black text, and so
a healthy boot was dressed as a crash and then abruptly became an amber

7
docs/architecture/kernel.md
View file

@ -438,6 +438,13 @@ allocation over 8 MB mapped straight into a neighbouring live mapping.
- **Permissions are tracked but not enforced.** uid/gid are maintained honestly
so `getuid()`/`setuid()` stop lying, and file access does not consult them;
`setpriority` is the one place the uids are checked.
- **`mprotect` is accepted and not enforced** (`sys_mprotect` returns 0). RELRO is not read-only,
a `PROT_NONE` guard does not fault, and nothing has `NX` (`EFER.NXE` is never set), so every
mapping is executable.
- **`poll`, `select` and `epoll` wait a tick at a time** (10 ms at `HZ=100`) unless something
that can make a descriptor ready calls `poll_kick()` — which the pipe, socket and event paths
do. busybox's `wget` polls before every read and downloaded at 85 KB/s, a segment per tick,
until the network path started kicking.
- **No swap**, and no memory pressure handling of any kind. `kalloc` failing is
reported up as `-ENOMEM` and that is the whole policy.
- **Nested signal delivery is not supported.** `in_signal` guards against

2
docs/architecture/ldls.md
View file

@ -330,7 +330,7 @@ one flag and hands over all 65536 ports, including the interrupt controller,
the timer and the disk; the TSS I/O permission bitmap is per port. A foreign
driver already has DMA with no IOMMU, and the answer to "this is not a security
boundary" is not to move it further — so it is the bitmap, at 8 KB per CPU of
resident memory. See [../../include/ioperm.h](../../include/ioperm.h).
resident memory. See [../../include/arch/ioperm.h](../../include/arch/ioperm.h).
Writing it found a latent hole. The TSS's I/O map base is at offset 102 and the
old code wrote offset 64; the field it meant to set stayed 0, and a base of 0

2
docs/architecture/networking.md
View file

@ -168,7 +168,7 @@ Recorded because both would have worked, quietly:
## The netdev class
A driver publishes a [`struct netdev_ops`](../../include/netdev.h) and is then
A driver publishes a [`struct netdev_ops`](../../include/dev/netdev.h) and is then
finished with the network stack forever: it never mentions lwIP, and the stack
never mentions it.

10
docs/architecture/terminals.md
View file

@ -272,12 +272,10 @@ Three layers, in increasing order of how much a program is claiming:
`VT_SETMODE` used to be accepted and ignored — a program could ask for the
chord, be told yes, and still not get it. It works now.
What `VT_PROCESS` does **not** do yet is the release handshake: Linux signals
the owning process on every switch request and blocks until it answers
`VT_RELDISP`, which is how a display server releases the GPU before the screen
changes hands. Nothing here has anything to release, so the kernel simply
stops switching rather than negotiating. `struct vt_mode` already carries
`relsig`/`acqsig` for when Schcom needs it.
`VT_PROCESS` also does the release handshake Linux does: a switch away from a terminal in
that mode signals the owning process (`relsig`) and waits for `VT_RELDISP`, which is how a
display server stops drawing before the screen changes hands; switching back sends `acqsig`.
See *Handing a terminal to a program*, below.
Input goes to whichever terminal is on screen. That is what makes a terminal a
terminal: the keyboard follows the eyes.

2
docs/architecture/usb.md
View file

@ -28,7 +28,7 @@ framework underneath, not the licence.
## What the spec gives you for free
Everything in [`include/dev/usb.h`](../../include/usb.h) comes from USB 2.0
Everything in [`include/dev/usb.h`](../../include/dev/usb.h) comes from USB 2.0
chapter 9, which every device implements regardless of speed, class or vendor.
**That is what makes enumeration possible at all:** before you know anything