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
166 lines
6.9 KiB
Markdown
166 lines
6.9 KiB
Markdown
<div align="center">
|
||
|
||
<img src="Assets/SchOS%20Full%20Logo.png" alt="SchOS" width="360">
|
||
|
||
**A 64-bit operating system, written from the metal up.**
|
||
|
||
SMP · copy-on-write filesystem · TCP/IP · PCI, USB and virtio drivers · TrueType text · Linux syscall ABI
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
SchOS began as [xv6](https://github.com/mit-pdos/xv6-public) and is now mostly
|
||
something else. The scheduler, the memory manager and the trap path have been
|
||
rewritten for x86-64 and for more than one processor; the filesystem has been
|
||
replaced outright; the syscall table speaks Linux numbering so that real
|
||
software — musl, toybox, mksh — runs unmodified.
|
||
|
||
It is a hobby system built by one person, and it is honest about that: what
|
||
works below has been *run*, not inferred, and the gaps are listed as plainly as
|
||
the features.
|
||
|
||
## The pieces
|
||
|
||
| Layer | Name | What it is |
|
||
|---|---|---|
|
||
| System | **SchOS** | The distribution — kernel, userland, tooling |
|
||
| Kernel | **SchIFT** | Multi-core x86-64 kernel with a modular VFS |
|
||
| Filesystem | **SchFS** | Transactional, copy-on-write, the root filesystem |
|
||
| API | **SchAPI** | System programming interface — the stable surface |
|
||
| Compositor | **SchCom** | Display compositor *(planned)* |
|
||
| Window manager | **SchWM** | *(planned)* |
|
||
| Desktop | **SchDE** | *(planned)* |
|
||
|
||
`uname -s` reports `SchIFT`, the way every Unix reports its kernel rather than
|
||
its distribution.
|
||
|
||
## What works
|
||
|
||
**Kernel** — Long mode, 4-level paging, preemptive multitasking. **SMP**: one,
|
||
two and four processors all boot, with CPU enumeration from the ACPI MADT rather
|
||
than the 1994 MP table. Memory sized from the E820 map, so it runs in tens of
|
||
megabytes rather than demanding hundreds.
|
||
|
||
**Filesystem** — **SchFS** is the root: a copy-on-write B-tree with a
|
||
uberblock ring, so a crash leaves either the old tree or the new one and there
|
||
is nothing to repair. Free space is derived from the tree rather than stored
|
||
beside it, which removes a whole class of disagreement. `/proc/schfs` shows the
|
||
generation counter advancing as writes commit.
|
||
|
||
**Processes** — fork, exec, wait, pipes, signals, sessions and process groups,
|
||
`mmap` (anonymous and file-backed), POSIX shared memory, Unix domain sockets,
|
||
`poll`.
|
||
|
||
**Devices** — PCI enumeration with a bus-agnostic device model at
|
||
`/proc/devices`. Drivers for **e1000** networking, **virtio-gpu** and stdvga
|
||
displays, **xHCI** USB with HID, hub and mass-storage class drivers, IDE, PS/2,
|
||
serial. `/dev/fb0` speaks the Linux fbdev interface.
|
||
|
||
**Networking** — ARP, IPv4, ICMP, UDP, TCP and DHCP, on lwIP behind a
|
||
driver-agnostic interface class. Verified end to end from the host, both
|
||
directions, rather than by inspection.
|
||
|
||
**Userland** — musl, toybox and mksh, built from source. `ls`, `cat`, `ps`,
|
||
`top`, `wc`, `cp`, `mount` and the rest behave the way you expect, because they
|
||
are the real programs.
|
||
|
||
**Text** — a TrueType rasteriser (`glyf` outlines, composite glyphs, cmap
|
||
format 4) replacing the 8×16 cell grid. JetBrains Mono for the terminal, Roboto
|
||
for the desktop layer to come.
|
||
|
||
**When it dies** — PSOGM, the Purple Screen of Guru Meditation: stop code,
|
||
fault address, call chain, and a QR code containing a text copy of the whole
|
||
report.
|
||
|
||
## Quick start
|
||
|
||
```sh
|
||
make # kernel + UEFI loader + root filesystem
|
||
make qemu # build it and boot it
|
||
make iso # a bootable ISO for VMware or real hardware
|
||
```
|
||
|
||
Builds on **Linux, macOS, FreeBSD/OpenBSD/NetBSD and Windows** (Git Bash). The
|
||
toolchain is clang + lld everywhere — it is a cross-compiler by construction, so
|
||
one LLVM install targets the bare-metal kernel, the 16-bit boot code and musl
|
||
userland from any host. See **[docs/guides/building.md](docs/guides/building.md)** for
|
||
prerequisites per platform, and
|
||
**[docs/history/moving-to-linux.md](docs/history/moving-to-linux.md)** for moving a checkout
|
||
between machines.
|
||
|
||
## Testing
|
||
|
||
Booting to a prompt proves nothing: a filesystem can mount and still fail the
|
||
first real command, and that has happened here. So the test harness drives the
|
||
serial console and asserts on what comes back.
|
||
|
||
```sh
|
||
tools/windows/bootcheck.ps1 # boot, run real commands, check the answers
|
||
tools/windows/bootcheck.ps1 -Tty -Ps # terminal behaviour, process enumeration
|
||
make schfs-check # SchFS B-tree, object and image suites
|
||
```
|
||
|
||
`bootcheck` is PowerShell because `pwsh` runs on every supported host.
|
||
|
||
## Layout
|
||
|
||
```
|
||
kernel/ arch/ core/ dev/ drivers/ fs/ net/ proc/ sys/
|
||
fs/schfs/ the filesystem -- same source the host tools compile
|
||
include/ kernel and userland headers
|
||
boot/ uefi/ (PE loader) common/ (shared loader UI)
|
||
lib/ cmd/ first-party userland runtime and programs
|
||
ports/ third-party software built from source
|
||
tools/ windows/ (.ps1) posix/ (.sh) python/ (.py) and .c/.pl
|
||
docs/ architecture/ (what it is) plan/ (what's next)
|
||
guides/ (how to work on it) history/ (why it's like this)
|
||
```
|
||
|
||
**[docs/README.md](docs/README.md)** is the index. If you are reading the tree
|
||
for the first time, [docs/architecture/README.md](docs/architecture/README.md)
|
||
is the system layer by layer.
|
||
|
||
One rule worth knowing: **the kernel and the host tools compile the same SchFS
|
||
source**. `mkschfs` cannot disagree with the kernel about the on-disk format,
|
||
because there is only one implementation — found and fixed on the host, where a
|
||
test takes a second instead of a boot.
|
||
|
||
Another: **syscalls are declared in exactly one place**,
|
||
`kernel/sys/table.inc`. Everything else is generated from it.
|
||
|
||
## Not there yet
|
||
|
||
- **No desktop.** Schcom composites and routes input; the plan is now to put it
|
||
on Wayland and delete the homegrown protocol. See
|
||
[docs/plan/wayland.md](docs/plan/wayland.md).
|
||
- **No descriptor passing.** No `sendmsg`/`recvmsg`, so no `SCM_RIGHTS` — which
|
||
is what the GUI work stops at. [docs/plan/foundations.md](docs/plan/foundations.md).
|
||
- **No dynamic linking.** `exec` handles static `ET_EXEC` only.
|
||
- **No page cache**, so writable `MAP_SHARED` of a file is refused rather than
|
||
faked.
|
||
- **A USB disk cannot be booted from** — the root device is compiled in rather
|
||
than selectable.
|
||
- SchFS has no Linux driver yet; the plan is on-disk format version first, then
|
||
FUSE, then a kernel module.
|
||
- CFF/OpenType outlines and TrueType hinting are deliberately out of scope.
|
||
|
||
## Licensing
|
||
|
||
**Apache-2.0**, copyright Nexoniarz. See [LICENSE](LICENSE).
|
||
|
||
The kernel derives from xv6, which is MIT — see [LICENSE.MIT](LICENSE.MIT).
|
||
Third-party code redistributed in a built image (musl, toybox, mksh, the fonts)
|
||
keeps its own licence; [NOTICE](NOTICE) carries the attributions.
|
||
|
||
Drivers may be adapted from BSD sources, which are compatible. Linux drivers are
|
||
not: GPL-2.0-only and Apache-2.0 cannot be combined and redistributed. Reading
|
||
Linux to understand hardware is fine; translating a driver is not. Best of all
|
||
is the public specification — xHCI, virtio, AHCI, e1000 — which carries no
|
||
licence on what you write from it.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>Built with stubbornness and a serial console.</sub>
|
||
</div>
|