From 47c021ef7e60ab64ba7c66ef38982e3e644de154 Mon Sep 17 00:00:00 2001 From: Nexoniarz Date: Sun, 9 Aug 2026 14:41:35 +0200 Subject: [PATCH] README What SchOS is, what actually runs, and what does not. The feature list is restricted to things that have been run rather than inferred, and the gaps get their own section -- a hobby OS README that overclaims is worse than none. --- README.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bbc9973 --- /dev/null +++ b/README.md @@ -0,0 +1,148 @@ +
+ +SchOS + +**A 64-bit operating system, written from the metal up.** + +SMP · copy-on-write filesystem · 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. + +**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 + bootloader + root filesystem -> schos.img +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/building.md](docs/building.md)** for +prerequisites per platform. + +## 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/ bootblock and stage 2 (VBE splash, boot menu) +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, roadmap, licensing, building +``` + +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 TCP/IP. The decision is made — port lwIP rather than write one — but it is + not done. The e1000 driver works; nothing speaks to it yet. +- No compositor, window manager or desktop. That is the next large piece. +- 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. + +--- + +
+Built with stubbornness and a serial console. +