c0ed23cc56
The failure this is against is not scope creep. It is abandonment by promotion:
a thing gets built to the point where it works, the next thing becomes more
interesting, and the first is left in a corner -- in the tree, not finished, not
deleted, and not in any list. Enough of those and the tree stops matching its
own documentation.
docs/plan/1.0.md now holds the register, and it is the only place anything
half-built is listed. Four sections, because the kinds are genuinely different:
built and connected to nothing (the text layer, a font from disk, socket
activation, wait_vblank); started and stopped part-way (foundations 2-5, hybrid
H2, Schcom v0, a released PCI device that nothing brings back); named in a "what
it does not do" and still true; and frozen -- scoped, unstarted, not to be
started. The rule is that nothing enters except by being finished or deleted,
and that adding a row requires closing one.
1.0.md already said "two things in flight, never three". It was right and it was
not being followed.
Then the corners themselves, because a register written over a tree full of them
is just a longer list:
- cmd/init is deleted. Nothing had execed /bin/init since initcode.S changed
to /bin/schinit; it was built and installed on every image as an unreachable
fallback, and an unreachable fallback rots rather than saves.
- projects/schwm/ and projects/schde/ are deleted. Both said "to be deleted"
in their own first paragraph, which proves only that a directory marked for
deletion is not deleted by being marked. README-only, no code lost, and the
arguments each made are moved into wayland.md where they are still true.
- projects/schcom/schcom and schcom-demo were tracked binaries. Untracked, and
.gitignore'd.
Three code comments and one document described a boot that has not happened
since 7d44eb7. cons_serial_only starts set, but kmain clears it on its first
lines now, so the splash does not survive the boot and the kernel log is on
screen from the start. That reversal was earned by a Chromebox with no serial
port freezing at boot showing nothing at all, and the comments still argued the
losing side of it.
The site:
- a download page. One ISO, what it has actually been run on -- one machine,
under test -- Ventoy and dd, what the first boot looks like step by step,
and the build if you would rather. The support table names one Chromebox
rather than listing hardware, because one Chromebox is the entire bare-metal
record and a list would be fiction.
- Assets/usb.svg, drawn to the same rule as the other marks: two tones,
geometry only, the accent spent in one place, and that place is the activity
light because it is the part that tells you something is happening.
- Download is in both navs and is the hero's primary action; a closing band
ends the front page on it.
- the uberblock-slots and drivers-outside-the-kernel figures are gone. Three
numbers left, including the fastfetch one, which stays because it is funny.
Two things caught by rendering the pages instead of assuming: .hero p was
beating .filemeta on specificity and the file line was coming out at body size,
and the dd command was one line long enough that the card clipped it at `conv=`
-- a destructive command that can scroll half of itself out of view is a good
way to take somebody's disk. It is two lines now.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
110 lines
5.5 KiB
Markdown
110 lines
5.5 KiB
Markdown
# Schcom — the SchOS Compositor
|
||
|
||
Owns the display. Every pixel that reaches the screen goes through it.
|
||
|
||
Clients do not draw to the framebuffer; they draw into their own buffers and
|
||
hand them over. Schcom decides what is on top of what, composites the result,
|
||
and presents it. It also owns input: it reads the raw event devices and sends
|
||
each event to whichever client should have it.
|
||
|
||
That is the whole job. Window *placement* is not part of it — that is SchWM's,
|
||
and Schcom exposes a protocol for it rather than implementing policy itself.
|
||
|
||
## Status
|
||
|
||
**v0 runs.** A client connects, is given a shared buffer, draws into it and
|
||
commits; the result is composited and presented. Verified end to end by
|
||
`make schcom-test`, which boots SchOS, runs the compositor and a client, then
|
||
screendumps the framebuffer and asserts the pixels **from the host** — the
|
||
compositor's own report that it composited something proves nothing. It runs
|
||
two overlapping clients and checks that the newer one wins in the overlap: a
|
||
compositor that cannot order two surfaces cannot host a window manager.
|
||
|
||
What exists:
|
||
|
||
- framebuffer output through `/dev/fb0` and the fbdev ioctls, double-buffered
|
||
- a versioned protocol over a Unix socket, with a handshake that must come first
|
||
- shared-memory buffers, one per surface, owned by the compositor
|
||
- surface / attach / **commit** semantics: nothing is shown mid-draw
|
||
- input from `/dev/input/eventN`, routed to the topmost surface
|
||
- clients that die are cleaned up, including their shm segments
|
||
- **multiple clients**, composited bottom-to-top in creation order
|
||
|
||
What does not exist yet: damage tracking beyond "repaint everything", multiple
|
||
outputs, subsurfaces, and any focus model beyond "topmost". Those are additions
|
||
rather than rewrites, which is the reason for committing to the surface/commit
|
||
model now instead of growing into it later.
|
||
|
||
## Building
|
||
|
||
Not part of the OS build. Needs `make ports` first, for the sysroot's libc:
|
||
|
||
```sh
|
||
make projects # builds and stages into sysroot/bin
|
||
make # rebuilds the image so the binaries are on it
|
||
make schcom-test # boots it and checks the pixels
|
||
```
|
||
|
||
## What it needs from the kernel
|
||
|
||
| Need | State |
|
||
|---|---|
|
||
| Shared memory (`shmget`/`shmat`/`shmdt`) | done |
|
||
| `mmap` of `/dev/fb0` | done |
|
||
| Framebuffer geometry via the fbdev ioctls | done |
|
||
| Unix domain sockets | done |
|
||
| Raw input events — key down/up with modifiers | done |
|
||
| `SCM_RIGHTS` | done — `sendmsg`/`recvmsg`, see [`docs/architecture/networking.md`](../../docs/architecture/networking.md#descriptor-passing) |
|
||
| A shareable memory object | **missing.** A Wayland buffer is a descriptor for memory; a System V segment id is not one. Item 2 of [`docs/plan/foundations.md`](../../docs/plan/foundations.md), and the one thing now standing between this directory and a Wayland compositor. |
|
||
| Mode setting and double buffering | partial — virtio-gpu binds, no modeset API yet |
|
||
|
||
> **The v0 protocol below is superseded and the code is frozen.** It runs, and
|
||
> it is kept because it is the only thing in the tree that has ever composited
|
||
> anything — but nothing more will be added to it. SchWM and SchDE are referred
|
||
> to throughout and both have been deleted; read those mentions as "the policy
|
||
> module" and "a layer-shell client". See
|
||
> [`docs/plan/wayland.md`](../../docs/plan/wayland.md).
|
||
|
||
## Design notes
|
||
|
||
- **Buffers are shared memory, not pipes.** A pipe means copying every frame; at
|
||
800×600×32 that is 1.9 MB per frame per client.
|
||
- **The compositor owns the segment, not the client.** It has to survive a
|
||
client crashing mid-frame, and it must not be something a client can resize
|
||
underneath the compositor.
|
||
- **One protocol, versioned from the start.** SchWM and SchDE are separate
|
||
programs, so this is a real compatibility surface on day one. Every message
|
||
carries its own length, so an unknown message is skipped rather than
|
||
desynchronising the stream — that is what lets a v0 compositor survive a v1
|
||
client.
|
||
- **Policy belongs to SchWM.** If Schcom starts deciding where windows go, the
|
||
split has already failed. `CREATE_SURFACE` carries x/y today only because
|
||
there is no SchWM yet to ask.
|
||
|
||
## On Wayland
|
||
|
||
> **Decided: Schcom moves onto Wayland**, replacing the protocol below while
|
||
> keeping the architecture. See [`docs/plan/wayland.md`](../../docs/plan/wayland.md).
|
||
|
||
|
||
The protocol is deliberately Wayland-shaped — surfaces rather than windows,
|
||
buffers attached and made visible only on commit, and the compositor telling
|
||
clients when to draw. Wayland is **MIT-licensed**, so it can be linked against
|
||
without any conflict with Apache-2.0 (see `docs/licensing.md`), and
|
||
supporting it later is intended.
|
||
|
||
The one place v0 knowingly diverges: a buffer handle is a System V shared memory
|
||
id passed as an integer, where Wayland passes a file descriptor over
|
||
`SCM_RIGHTS`. `struct schcom_surface` carries a `handle_kind` field precisely so
|
||
that switching would be a new value rather than a protocol break.
|
||
|
||
**That field could not have saved us.** Wayland's `wl_shm_create_pool` passes a
|
||
descriptor with no alternative form, so *our* protocol being the flexible one
|
||
was never the flexibility that was needed — and for a long time this README
|
||
claimed `SCM_RIGHTS` was done when there was no `sendmsg`/`recvmsg` in the
|
||
kernel at all. An entire GUI plan was drawn on top of that line.
|
||
|
||
It is true now. Item 1 of
|
||
[`docs/plan/foundations.md`](../../docs/plan/foundations.md) is built and
|
||
tested; what a buffer still needs is item 2, a shareable memory object, because
|
||
a descriptor for a System V segment is not a thing that exists.
|