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. +