# 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.