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
105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# What happens next
|
||
|
||
Everything in this directory is **unbuilt**. When a piece of it is finished it
|
||
leaves — deleted from here, rewritten as a description in
|
||
[../architecture/](../architecture/). See [the rule](../README.md#the-rule-that-keeps-this-from-rotting).
|
||
|
||
> ## Read [1.0.md](1.0.md) first.
|
||
>
|
||
> It draws a finish line and puts most of the work below on the far side of it.
|
||
> **Anything not named there is not being worked on**, and the documents in this
|
||
> directory describe more than 1.0 contains.
|
||
|
||
---
|
||
|
||
## The three current decisions
|
||
|
||
Taken together, because they turn out to need the same foundation.
|
||
|
||
| | |
|
||
|---|---|
|
||
| **[wayland.md](wayland.md)** | The GUI stack becomes Wayland. SchWM and SchDE are deleted; Schcom survives and changes its wire format. |
|
||
| **[hybrid.md](hybrid.md)** | The kernel becomes hybrid — drivers move out into userspace processes, starting with the GPU. |
|
||
| **[init.md](init.md)** | PID 1 stops being a process and becomes a role the kernel guarantees is filled. |
|
||
|
||
And the one they all wait on:
|
||
|
||
| | |
|
||
|---|---|
|
||
| **[foundations.md](foundations.md)** | Descriptor passing, shared memory, sockets in the filesystem. The critical path. |
|
||
|
||
And the one that says which parts of the above are actually being worked on:
|
||
|
||
| | |
|
||
|---|---|
|
||
| **[1.0.md](1.0.md)** | The finish line. Four gates, and everything else explicitly deferred. |
|
||
|
||
Two longer-horizon documents sit behind these: [schapi.md](schapi.md), the API
|
||
layering and the compatibility promise, and [roadmap.md](roadmap.md), which holds
|
||
everything still open that is not one of the three above.
|
||
|
||
---
|
||
|
||
## The order
|
||
|
||
Set by [1.0.md](1.0.md), which is the authority. In short:
|
||
|
||
### 0. Fix what is already wrong — **first**
|
||
|
||
Not a document of its own; it is Gate 0 of [1.0.md](1.0.md), assembled from the
|
||
*What it does not do* sections in [../architecture/](../architecture/).
|
||
|
||
**Before any new capability**, and the reason is the one that put
|
||
`netdev_selftest()` before the TCP/IP stack: a compositor built on a kernel with
|
||
an unexplained hang and a socket layer that reports success for things it did not
|
||
do will fail in ways indistinguishable from its own bugs.
|
||
|
||
### 1. `foundations.md` — the critical path
|
||
|
||
Both the Wayland work and the hybrid work stop here. Descriptor passing and
|
||
shared memory are the substrate for handing a buffer to a compositor *and* for
|
||
handing a device to a driver process. **Doing it once for both is the entire
|
||
reason these are one plan rather than three.**
|
||
|
||
### 2. `init.md` — before the desktop, not after
|
||
|
||
A compositor being brought up for the first time crashes constantly, and
|
||
something that restarts it and says why is worth far more during that work than
|
||
at the end of it.
|
||
|
||
### 3. `wayland.md` — with the GPU driver still in the kernel
|
||
|
||
W1–W3 and a terminal. W4 and W5 are post-1.0.
|
||
|
||
### 4. `hybrid.md` — **after 1.0**
|
||
|
||
Deliberately last: **designing a userspace driver interface with no driver
|
||
consuming it produces an interface that is wrong in ways nobody can see.** The
|
||
compositor is the demanding consumer that makes the interface judgeable, so it
|
||
has to exist first.
|
||
|
||
---
|
||
|
||
## In one sentence
|
||
|
||
> Fix what is broken, build the descriptor-passing and shared-memory substrate,
|
||
> make init survivable, put a terminal on the screen — and only then use the
|
||
> compositor as the pressure that shapes the userspace driver interface.
|
||
|
||
---
|
||
|
||
## What this plan does not address
|
||
|
||
Stated here so it is not mistaken for covered:
|
||
|
||
- **No IOMMU**, so the hybrid work isolates against bugs and not against a
|
||
hostile driver.
|
||
- **No page cache**, so `foundations.md` delivers a `memfd` and not a general
|
||
answer to shared file mappings. The general answer is still owed.
|
||
- **No dynamic linking**, so no Mesa, no accelerated clients, and no third party
|
||
shipping a `.so` for anything.
|
||
- **A new compatibility surface** between PID 1 and PID 2, created by a plan
|
||
whose own [schapi.md](schapi.md) §3 spends a section warning about those.
|
||
- **The three open networking items** — `getsockname`, routing, and
|
||
interrupt-driven receive — are untouched by any of this and still open. They
|
||
are in [roadmap.md](roadmap.md).
|