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
129 lines
5.9 KiB
Markdown
129 lines
5.9 KiB
Markdown
# SchOS documentation
|
|
|
|
Four kinds of document, kept in four directories, because they answer four
|
|
different questions and go stale at four different rates.
|
|
|
|
| | | |
|
|
|---|---|---|
|
|
| **[architecture/](architecture/)** | *What SchOS is* | Present tense. Describes what is built and working. |
|
|
| **[plan/](plan/)** | *What SchOS will be* | Future tense. Everything here is unbuilt. |
|
|
| **[guides/](guides/)** | *How to work on it* | Imperative. Build it, test it, add to it. |
|
|
| **[history/](history/)** | *Why it is the way it is* | Past tense. Bugs whose cause is not visible from the fix. |
|
|
|
|
Plus one rule that belongs to no category and applies to everything:
|
|
**[licensing.md](licensing.md)** — read it before copying anyone else's code in.
|
|
|
|
---
|
|
|
|
## The rule that keeps this from rotting
|
|
|
|
> **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 completed item is not a ticked checkbox. A ticked checkbox says the work
|
|
happened; it does not say what the work *produced*, and six months later the
|
|
checkbox is the only thing left and it explains nothing.
|
|
|
|
So finishing a piece of work has three steps, and the third is not optional:
|
|
|
|
1. The code works and is tested.
|
|
2. The plan entry is deleted.
|
|
3. A description exists in `architecture/` written for somebody who was not
|
|
there — what it does, what shape it has, what it costs, and what it still
|
|
does not do.
|
|
|
|
This is not bookkeeping. The tree has already proved it necessary: the network
|
|
stack was finished, verified end to end, and for a month afterwards the only
|
|
description of it anywhere was a checkbox in a roadmap, four levels of
|
|
indentation deep, written in the past tense of somebody arguing for the work
|
|
rather than explaining the result.
|
|
|
|
**The "what it does not do" section is the one that pays.** Every description in
|
|
`architecture/` ends with one. A document that only lists a subsystem's
|
|
strengths is marketing, and the reader who most needs the document is the one
|
|
about to trip over a limitation nobody wrote down.
|
|
|
|
---
|
|
|
|
## Start here
|
|
|
|
**New to the tree** → [architecture/README.md](architecture/README.md), the
|
|
system layer by layer, then [guides/layout.md](guides/layout.md) for where the
|
|
files are.
|
|
|
|
**Trying to build it** → [guides/building.md](guides/building.md).
|
|
|
|
**Wondering what happens next** → [plan/1.0.md](plan/1.0.md), which is the finish line, then [plan/README.md](plan/README.md) for the order.
|
|
|
|
**Something is broken and it feels familiar** → [history/](history/). There is a
|
|
good chance it is in there.
|
|
|
|
---
|
|
|
|
## architecture/ — what SchOS is
|
|
|
|
| | |
|
|
|---|---|
|
|
| [README](architecture/README.md) | The system, layer by layer. Read first. |
|
|
| [boot.md](architecture/boot.md) | Firmware to the first userspace process. |
|
|
| [kernel.md](architecture/kernel.md) | SchIFT: memory, processes, scheduling, traps, signals, SMP. |
|
|
| [syscalls.md](architecture/syscalls.md) | The call table, and the Linux personality that lets real software run. |
|
|
| [filesystem.md](architecture/filesystem.md) | The VFS, the buffer cache, procfs, mounts. |
|
|
| [schfs.md](architecture/schfs.md) | SchFS: the copy-on-write root filesystem. |
|
|
| [devices.md](architecture/devices.md) | The device model, driver binding, the class vtables. |
|
|
| [usb.md](architecture/usb.md) | xHCI, the USB core, and the class drivers. |
|
|
| [graphics.md](architecture/graphics.md) | Framebuffer, text rendering, console, and the crash screen. |
|
|
| [networking.md](architecture/networking.md) | Drivers, lwIP, sockets — Unix and INET. |
|
|
| [init.md](architecture/init.md) | `schinit`, PID 1, and the job manifests. |
|
|
|
|
## plan/ — what SchOS will be
|
|
|
|
| | |
|
|
|---|---|
|
|
| [README](plan/README.md) | The three current decisions and the order they happen in. |
|
|
| [1.0.md](plan/1.0.md) | **The finish line.** What 1.0 contains, and what is explicitly deferred past it. |
|
|
| [foundations.md](plan/foundations.md) | The kernel work everything else is blocked on. |
|
|
| [init.md](plan/init.md) | PID 1 becomes a role rather than a process. |
|
|
| [wayland.md](plan/wayland.md) | The GUI stack, and what gets deleted to make room. |
|
|
| [hybrid.md](plan/hybrid.md) | Moving drivers out of the kernel. |
|
|
| [schapi.md](plan/schapi.md) | The long-term API layering, and the compatibility promise. |
|
|
| [roadmap.md](plan/roadmap.md) | Everything else still open. |
|
|
|
|
## guides/ — how to work on it
|
|
|
|
| | |
|
|
|---|---|
|
|
| [building.md](guides/building.md) | Prerequisites and the build, per host. |
|
|
| [testing.md](guides/testing.md) | The harnesses, and what each one actually proves. |
|
|
| [layout.md](guides/layout.md) | Repository map, and how to add a program or a port. |
|
|
| [adding-a-driver.md](guides/adding-a-driver.md) | Writing one, binding it, publishing its class vtable. |
|
|
|
|
## history/ — why it is the way it is
|
|
|
|
| | |
|
|
|---|---|
|
|
| [README](history/README.md) | What belongs in here and what does not. |
|
|
| [kernel.md](history/kernel.md) | Bugs whose cause was nowhere near their symptom. |
|
|
| [moving-to-linux.md](history/moving-to-linux.md) | The Windows-to-Fedora move, kept for the parts that recur. |
|
|
|
|
---
|
|
|
|
## Writing one of these
|
|
|
|
Four conventions, all of them observable in the existing files:
|
|
|
|
**State the cost.** Every design choice gave something up. A document that does
|
|
not say what is a document that will be argued with later by somebody who only
|
|
sees the downside.
|
|
|
|
**Prefer the measured number to the remembered one.** "500 of 3565 files carry
|
|
the advertising clause" is worth more than "some do", and it was worth the
|
|
minute it took to count.
|
|
|
|
**Write down the bug that shaped it.** Half the non-obvious code in this tree is
|
|
non-obvious because something failed once. If a design is strange, the strangeness
|
|
is load-bearing and the reader deserves to know why before changing it.
|
|
|
|
**No dates in headings.** A date in a heading turns a description into a
|
|
changelog, and the description is the thing with a long life. Dates belong in
|
|
`history/`, where they mean something.
|