# SchOS
**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
---
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. Names resolve, so `wget http://host/`
works; `httpd` serves a directory back the other way.
**Userland** — musl, toybox, mksh and zsh, built from source. 268 applets:
`ls`, `cat`, `ps`, `top`, `wc`, `cp`, `mount`, `awk`, `bc`, `diff` and the rest
behave the way you expect, because they are the real programs. `edit` is
[kilo](https://github.com/antirez/kilo) — arrow keys, Ctrl-S, Ctrl-Q, nothing
to learn.
**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, by subsystem (arch/ core/ fs/ dev/ ...)
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
**GPL-2.0-or-later**, 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, zsh, kilo,
the fonts) keeps its own licence; [NOTICE](NOTICE) carries the attributions.
See [docs/licensing.md](docs/licensing.md).
Drivers may be adapted from BSD sources and, since the move to the GPL, from
Linux — GPL-2.0-only code combines with GPL-2.0-or-later, and the result ships
under GPLv2. Best of all is still the public specification — xHCI, virtio,
AHCI, e1000 — which carries no licence on what you write from it.
---