| Filename | Latest commit message | Latest commit date |
|---|---|---|
a79dfac32b
Gate 1, item 2, and the thing a Wayland buffer crosses on.
memfd_create(2) is the same segment machinery shmget() already had -- pages,
refcounts, no_free VMAs, the fork and exit accounting -- reached by
**descriptor** rather than by System V key. That difference is the entire
point and the reason it exists on Linux at all: two processes share memory by
passing the fd over a socket, so neither has to agree on a path or race to
invent a key. It is also why SCM_RIGHTS had to be item 1.
docs/plan/foundations.md proposed exactly this and it was right: what memfd
adds on top of shmget is a segment that starts empty and is sized by
ftruncate(), and a file that owns one reference to it. FD_MEMFD, and
read/write/lseek/fstat all learn about it -- a descriptor that refuses read()
is a surprise nobody needs.
Three things are refused rather than faked, each the honest version of
something this kernel cannot do:
- MAP_PRIVATE on a memfd. Every caller is sharing on purpose; a private
mapping of an anonymous object is an expensive MAP_ANONYMOUS.
- Mapping past the end. Linux faults those pages in; there is no handler
here that could.
- Shrinking while mapped. Linux truncates the pages out from under the
mapper; here a freed page would stay mapped to memory somebody else now
owns.
Writable MAP_SHARED of a *real file* is still ENODEV. That needs a page cache,
and an anonymous object has no such contract to break -- which is precisely
why memfd is the narrow answer.
**cmd/memfdtest**, seventeen checks, written so a permissive implementation
cannot pass: an mmap that quietly returned private zeroed pages satisfies every
return code and fails the one assertion that matters, because the reader is a
different process. It ends with the combination the plan singled out -- a memfd
sent over a socketpair to a receiver that closes every inherited copy first,
maps only the descriptor that arrived, reads what the sender wrote and writes
back where the sender can see it.
Two things were found by writing that test, both of which had been refusing
everything that was not FD_INODE:
- sys_fstat() never reached filestat(), so the memfd branch there was
unreachable from the syscall that needs it. It also refused pipes and
sockets, and returned -1 (which musl reads as EPERM) rather than an errno.
- sys_lseek() the same, and SEEK_END needs a length that is not in an inode.
Verified: 40 consecutive runs leave MemFree at exactly the value it started
at -- 936656 kB before and after -- so nothing leaks across creation, dual
mapping, descriptor passing and exit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
| .. | ||
| boot.md | ||
| debugging.md | ||
| devices.md | ||
| filesystem.md | ||
| graphics.md | ||
| init.md | ||
| kernel.md | ||
| ldls.md | ||
| networking.md | ||
| README.md | ||
| schfs.md | ||
| syscalls.md | ||
| terminals.md | ||
| usb.md | ||
The system, layer by layer
What SchOS is today. Everything in this directory is built and running; what is merely intended lives in ../plan/.
The names, and what each one covers
uname -s reports SchIFT, the way every Unix reports its kernel rather than
its distribution.
| 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 | The native programming interface — designed, not built |
| Compositor | Schcom | Owns the display; v0 runs |
Six virtual terminals sit under all of it -- /dev/tty1..tty6, AltGr+F1..F6
or chvt N --
each with its own screen, line discipline and foreground process group. See
terminals.md.
The stack, bottom to top
┌─────────────────────────────────────────────────┐
│ toybox kilo mksh zsh musl first-party cmd/ │ userland
├─────────────────────────────────────────────────┤
│ vgpud — a driver that is an ordinary process │
├─────────────────────────────────────────────────┤
│ schinit — PID 1, job manifests, supervision │
├─────────────────────────────────────────────────┤
│ syscall table — Linux numbering, one .inc file │ ← the ABI seam
╞═════════════════════════════════════════════════╡
│ VFS │ sockets │ signals │ mmap │ poll │ procfs │
├──────┴─────────┴─────────┴──────┴──────┴────────┤
│ SchFS │ lwIP │ vt/gfx │ buffer cache │
├─────────┴────────┴──────────┴───────────────────┤
│ device model — class vtables, bus binding │ ← the driver seam
├─────────────────────────────────────────────────┤
│ /dev/pci — MMIO, DMA and IRQs to a process │ ← the eviction seam
├─────────────────────────────────────────────────┤
│ drivers: xHCI e1000 virtio-gpu VBE IDE PS/2│
├─────────────────────────────────────────────────┤
│ scheduler │ paging │ traps │ IRQ │ SMP │ DMA │ SchIFT core
└─────────────────────────────────────────────────┘
▲
UEFI loader (boot/uefi)
Three seams matter. Above the syscall table, software is ordinary and
portable — musl and toybox are unmodified. Below the device model, a driver
never names its consumer and a consumer never names a driver. And at
/dev/pci, a driver stops having to be in the kernel at all: a process is
handed a device's registers, DMA memory and interrupts, and the in-kernel driver
that held it releases it cleanly. vgpud is the virtio-gpu driver living out
there today. See ../plan/hybrid.md.
Where it came from
SchOS began as xv6 and is now mostly something else. What survives from xv6 is the shape of the process table, the sleep/wakeup discipline, and the buffer cache. What has been replaced: the scheduler and trap path (rewritten for x86-64 and for more than one processor), the memory manager, the entire filesystem, the syscall layer, and every driver.
That inheritance is worth knowing when reading the code, because the parts that still look like xv6 follow xv6's conventions and the parts that do not, do not.
The documents
Read in this order if you are new:
| boot.md | Firmware to the first userspace process. The shortest path through the whole system. |
| kernel.md | Memory, processes, scheduling, traps, signals, SMP. |
| syscalls.md | The one table everything is generated from, and how a musl binary runs unmodified. |
| filesystem.md | The VFS, the buffer cache, mounts, procfs. |
| schfs.md | The copy-on-write root filesystem. |
| devices.md | Buses, classes, binding, and the vtables consumers talk to. |
| usb.md | xHCI, the USB core, and the three class drivers. |
| graphics.md | Framebuffer, text rendering, the console, and PSOGM. |
| terminals.md | The six virtual terminals, and the chord that switches them. |
| networking.md | NIC drivers, lwIP, and both socket families. |
| init.md | schinit, PID 1 as a role, and the job manifests. |
| debugging.md | Symbols, a log that outlives the kernel, and asking the kernel a question. |
| ldls.md | Running somebody else's drivers: a Linux .ko, in a process, reaching hardware through /dev/pci. |
Three rules that hold across all of it
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. Format bugs are found on the host, where a test takes a
second instead of a boot.
Syscalls are declared in exactly one place. kernel/sys/table.inc.
The constants, the dispatch table and the Linux translation map are all
generated from it, so a syscall cannot be half-registered.
A list you can read beats a list assembled by side effects. Drivers are
written out by hand in kernel/drivers/registry.c rather than collected by a
linker section, and platform devices are registered in one function rather than
inside each driver's init. The tradeoff is deliberate: self-registration is
nicer to write, and it means the list of what is in your kernel is not written
down anywhere you can read.