b08432b2c3
Four complaints, and only one of them was the thing it looked like. **"toybox is too small."** Half true, and the fix cost no licensing at all: 236 of toybox's applets are what defconfig builds, and the rest live in toys/pending/ -- awk, bc, diff, more, expr, tr, hexdump, stty among them. Same 0BSD tarball, switched off by a config default. 26 of them are on now, 236 -> 268. Not everything: strace wants ptrace, syslogd wants BSD's facilitynames[], git wants OpenSSL, and those three break the link. The toybox build also works again on this machine. Its scripts start #!/bin/bash, which does not exist on NixOS, so the binary in the tree was one nobody could reproduce; the shebangs are rewritten to /usr/bin/env bash on the way in. Pending applets are enabled by editing .config directly, because `make oldconfig` is the obvious way and undoes it -- every pending symbol is `default n`. **BusyBox was asked for and is not here.** It is GPL-2.0-only, and `make ramroot` links the root image *into the kernel binary*, so it would put GPLv2 inside an Apache-2.0 executable -- which is the exact case ports/Makefile's NOTPORTS filter and docs/licensing.md §4 exist for. nano is the same answer one version later. Both recorded in licensing.md with what was done instead, since "no" without an alternative is how a rule gets quietly broken later. **An editor that is not vi.** kilo, BSD-2-Clause, one 1300-line file, no dependencies beyond termios and TIOCGWINSZ, both of which zsh already needed. Installed as /bin/edit as well as /bin/kilo, because somebody with a file to fix will type `edit`. **"wget doesn't work."** Not a userland problem, and BusyBox's wget would have failed identically: nothing on this system could turn a name into an address, so every program taking a hostname failed in its own way and each looked like a separate bug. There is still no DNS client in SchOS and there does not need to be -- musl has a complete resolver and it works over ordinary UDP sockets. The one missing fact was which nameserver, which the kernel has had all along from DHCP and never published. /proc/resolv.conf publishes it in resolv.conf's exact syntax; cmd/resolvconf decides whether it becomes /etc/resolv.conf, and will not overwrite a hand-written one without -f. # wget -O - http://example.com/ | head -1 <!doctype html><html lang="en"><head><title>Example Domain</title> **Something to host with.** cmd/httpd: GET and HEAD, static files, index.html for a directory and a listing otherwise, a child per connection. No CGI, no keep-alive, no TLS, no config file. The path check is the only security-relevant code in it and it refuses rather than normalises -- no component may be `..`, and percent-decoding happens first, because %2e%2e is `..` and a check before decoding does not see it. Both forms answer 403. And the disk is 100 MB, from 32. It is sparse, so the image is 21 MB on the host. RAMDISK_BLOCKS went 6000 -> 8000 with it: the ramdisk was at 86% and the next thing added would have broken `make ramroot`, which nobody would have noticed until they used it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
172 lines
7.4 KiB
Markdown
172 lines
7.4 KiB
Markdown
<div align="center">
|
||
|
||
<img src="docs/branding/superseded-full-logo.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. 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
|
||
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, zsh, kilo,
|
||
the fonts) keeps its own licence; [NOTICE](NOTICE) carries the attributions.
|
||
All of it is permissive — there is no GPL in an image this builds, which is why
|
||
the userland is toybox and not BusyBox and the editor is kilo and not nano. See
|
||
[docs/licensing.md](docs/licensing.md).
|
||
|
||
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>
|