SchOS/docs/README.md

# 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 two that belong to no category and apply to everything:
**[licensing.md](licensing.md)** — read it before copying anyone else's code in —
and **[branding/](branding/)**, which holds the marks and the rules for using
them.

---

## 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 *and* the register of everything half-built. Then
[plan/README.md](plan/README.md) for the order.

**About to start something new** → the register, first. Nothing new starts while
it has rows in it, and a row leaves only by being finished or deleted.

**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, and where the loader puts the kernel. |
| [kernel.md](architecture/kernel.md) | SchIFT: memory, processes and threads, traps, signals, SMP. |
| [scheduler.md](architecture/scheduler.md) | Fair share by virtual runtime, slices, and `nice`. |
| [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, sysfs, devtmpfs, mounts. |
| [schfs.md](architecture/schfs.md) | SchFS: the copy-on-write root filesystem. |
| [scff.md](architecture/scff.md) | SCFF: the compressed image the live root ships as. |
| [fat.md](architecture/fat.md) | FAT12/16/32 with long names: USB sticks, SD cards, the ESP. |
| [devices.md](architecture/devices.md) | The device model, driver binding, the class vtables, and drivers that live in a process. |
| [ldls.md](architecture/ldls.md) | Running Linux's drivers: a `.ko` in a process, reaching hardware through `/dev/pci`. |
| [usb.md](architecture/usb.md) | xHCI, the USB core, and the class drivers. |
| [graphics.md](architecture/graphics.md) | Framebuffer, `/dev/fb0`, text rendering, the console, PSOGM and GMMOS. |
| [terminals.md](architecture/terminals.md) | The twelve virtual terminals, ptys, and handing one to a display server. |
| [audio.md](architecture/audio.md) | `/dev/dsp`, AudioEngine, AC'97, and ALSA over OSS. |
| [networking.md](architecture/networking.md) | NIC drivers, lwIP, sockets — Unix, INET and netlink. |
| [init.md](architecture/init.md) | `schinit`, PID 1 as a role, and the job manifests. |
| [packages.md](architecture/packages.md) | The apk root: Alpine's packages, and SchOS as one of them. |
| [desktop.md](architecture/desktop.md) | Xorg on the framebuffer, Window Maker, and what they stand on. |
| [debugging.md](architecture/debugging.md) | Symbols, a log that outlives the kernel, and asking the kernel a question. |

## plan/ — what SchOS will be

| | |
|---|---|
| [README](plan/README.md) | What is here, what used to be, and the order. |
| [1.0.md](plan/1.0.md) | **The finish line, and the freeze.** What 1.0 contains, where it stands, and the register of every half-built thing in the tree. |
| [roadmap.md](plan/roadmap.md) | Everything else scoped and still open. |
| [gpu.md](plan/gpu.md) | Linux's `amdgpu` through LDLS, and `/dev/dri` served by a process. |
| [finch.md](plan/finch.md) | The author's language for SchOS's own programs. |
| [schapi.md](plan/schapi.md) | The long-term API layering, and the compatibility promise. |

## 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. |
| [hardware-report.md](guides/hardware-report.md) | `hwreport`: describing a machine onto a USB stick, for whoever fixes it. |

## branding/ — the marks

| | |
|---|---|
| [README](branding/README.md) | Shift, the one mark: what it is for, the colour rule, why an icon and a mascot were removed, and why a raster is committed next to its SVG. |

## 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. |
| [schfs.md](history/schfs.md) | The filesystem's own, from the same period as its design. |
| [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.