SchOS/README.md

<div align="center">

<img src="docs/branding/shift.svg" alt="Shift, the SchOS mark" width="160">

# SchOS

**A 64-bit operating system, written from the metal up.**

SMP kernel · copy-on-write filesystem · Linux syscall ABI · Alpine packages · X11 on real hardware

</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 real Linux
software runs on it unmodified — statically or dynamically linked, straight
out of Alpine's package repositories.

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.

## In numbers

<!-- stats:begin -->
| | |
|---|---|
| **First-party code** | 61,367 lines, plus 21,128 lines of comments (26%) in 272 files |
| **Kernel** (`kernel/`, `include/`) | 45,207 lines of code, 16,111 of comments |
| **Syscalls** | 208, of which 184 on Linux numbering |
| **Drivers** | 15 in the kernel |
| **First-party programs** | 29 in `cmd/` |
| **Alpine packages in the root** | 88, from 11 asked for in `ports/alpine/world` |
| **History** | 253 commits since 2026-08-09 (76 days) |

<details>
<summary>Lines by language</summary>

| Language | Code | Comments |
|---|--:|--:|
| C | 56,580 | 19,427 |
| Assembly | 1,750 | 336 |
| PowerShell | 1,362 | 638 |
| Python | 759 | 147 |
| Shell | 716 | 469 |
| Perl | 129 | 45 |
| Linker script | 71 | 66 |

</details>

<sub>Measured by <code>tools/python/stats.py</code>; first-party code only, so
<code>ports/</code> and generated tables are not counted.</sub>
<!-- stats:end -->

## 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 |
| Image format | **SCFF** | The SchOS Compressed File Format the live root ships in |
| 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** up to
64 processors, enumerated from the ACPI MADT. ACPI through
[uACPI](https://github.com/uACPI/uACPI): interrupt routing from `_PRT`, the
power button, clean power-off and reset. Memory sized from the E820/UEFI map.

**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. The live image ships as **[SCFF](docs/architecture/scff.md)**:
the 358 MB root compresses to 102 MB with zstd and is unpacked a chunk at a
time, the first time something reads it. `/proc` has `/proc/<pid>/fd`,
`/proc/self` and the rest that `ps`, `top` and Xorg read.

**Processes** — fork, exec, wait, pipes, signals, sessions and job control,
`mmap` (anonymous and file-backed), POSIX shared memory, `memfd`, Unix domain
sockets with descriptor passing (`SCM_RIGHTS`), `poll`, `epoll`, `eventfd`,
`timerfd`, `signalfd`. **Dynamic linking**: `exec` loads `ld-musl`, so
binaries come from Alpine as they are.

**Packages** — the root is managed by Alpine's **apk**. `ports/alpine/world`
says what is installed; the build resolves it once into `world.lock` and every
image after that is reproducible. SchOS itself is one more package in it.

**Graphics** — **Xorg with Window Maker**, preinstalled, on the framebuffer
(`/dev/fb0`, Linux fbdev). Six virtual terminals, switched with
Ctrl+Alt+F1–F6 or Alt+F1–F6, with X on a terminal of its own; Ctrl+Alt+Backspace
ends the session. Input as Linux evdev on `/dev/input/event*`.

**Devices** — PCI with a bus-agnostic device model at `/proc/devices`.

| | |
|---|---|
| Storage | AHCI (SATA), NVMe, IDE, USB mass storage |
| Network | Intel e1000, Realtek r8169 and RTL8139 |
| USB | xHCI, hubs, HID keyboards and mice |
| Input | PS/2, I2C-HID laptop touchpads (DesignWare I2C, found through ACPI) |
| Display | UEFI GOP framebuffer, virtio-gpu, Bochs/stdvga |
| Audio | AC'97 |

**Networking** — ARP, IPv4, ICMP, UDP, TCP and DHCP on lwIP. DNS, `wget`
over **HTTPS**, `ping`, and an `httpd` serving a directory back.

**Userland** — musl, toybox, mksh and zsh, plus whatever Alpine has: `ls`,
`ps`, `top`, `awk`, `diff`, `xterm`, `fastfetch` behave the way you expect,
because they are the real programs.

**Text** — a TrueType rasteriser (`glyf` outlines, composite glyphs, cmap
format 4). JetBrains Mono for the terminal, Roboto for the desktop 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.

**On real hardware** — booted on an AMD B550 desktop (Ryzen 5 4600G), an ASUS
TUF A15 laptop and an Ivy Bridge HP all-in-one, from a USB stick.

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

The ISO is a hybrid image: write it to a USB stick with
`dd if=schos.iso of=/dev/sdX bs=4M` (or Rufus/Etcher in DD mode) and boot it
on any UEFI machine.

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.

The numbers at the top are measured, not typed: `python3 tools/python/stats.py`
rewrites them here and on the website.

## 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 threads.** `clone` makes processes, not threads (`CLONE_VM` is
  refused), so multi-threaded programs run on one thread or not at all. Xorg
  runs with `-dumbSched` for this reason.
- **No udev.** Xorg is told its input devices by a config file instead of
  finding them; `/sys` and the device-event socket are what is missing.
- **USB 2.0 controllers (EHCI)** have no driver. On older machines the ports
  wired only to EHCI do nothing; xHCI ports work.
- **Touchpads run in mouse mode**: pointer, click and tap, but no two-finger
  scroll yet.
- **No page cache**, so writable `MAP_SHARED` of a file is refused rather than
  faked. SysV shared memory is missing too.
- **No installer.** SchOS runs live from the USB stick; nothing is written to
  the machine's disks.
- 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.

---

<div align="center">
<sub>Built with stubbornness and a serial console.</sub>
</div>