SchOS/docs/architecture/syscalls.md

Syscalls, and the Linux personality

Two things happen at this boundary. SchOS has its own syscall numbering, and it also answers Linux's — which is why musl, toybox and mksh run unmodified.

---

One table, everything generated

Syscalls are declared in exactly one place: kernel/sys/table.inc. One line each.

SYSCALL(nr, linux_nr, name)     // implemented as sys_<name>()
SYSCALL_ALIAS(linux_nr, name)   // a second Linux number for the same handler

Three things are generated from it by macro expansion, and none is hand-maintained:

Generated	Where
The SYS_* constants	include/core/syscall.h
The dispatch table	kernel/sys/syscall.c
The Linux translation map	kernel/sys/linux_abi.c

Adding a syscall is therefore two edits: a line here, and a body written with SYSCALL_DEFINE(<name>) in one of the kernel/sys/sys_*.c files.

This replaced a two-place scheme and the reason is worth keeping. The Linux number used to live in a second hand-written table. Adding a syscall meant three edits across two files, and forgetting the second one left the call unreachable from every musl-linked program while looking perfectly registered in the first. A syscall can no longer be half-registered.

How a Linux binary runs

The translation is a flat array indexed by Linux syscall number, whose value is the native SYS_* number — or 0, meaning not implemented, which dispatches to -ENOSYS.

It is enabled per process, and selected automatically by exec():

// musl binaries have entry >= 0x100000; SchOS-native ones are linked at 0x4000
if (elf.entry >= LINUX_ABI_ENTRY_THRESHOLD)
    myproc()->syscall_map = linux_syscall_map;

A link address is a crude discriminator and it is honest about being one. It works because the two classes of binary in this system are linked by two different linker scripts at two very different addresses.

There is also enable_linux_abi() as an explicit call, which is why cmd/schinit/main.c carries a warning not to use it: doing so mid-process would renumber the syscalls the caller still has to make.

Native vs. Linux numbering

Some calls have no Linux equivalent and are marked NO_LINUX: sleep, uptime, reboot, shutdown, getmouse, vga_sync, schfs_index, schfs_query. These are reachable only from first-party programs linked against lib/.

They all land on the same scratch index in the translation array and overwrite each other there, which is harmless — no real Linux syscall uses that number, so the slot is never dispatched.

Where the two disagree on a name

shutdown is the one collision. SchOS has a native shutdown() that powers the machine off, and Linux number 48 is the socket call. Two syscalls cannot share a sys_ function name, so Linux 48 maps to sockshutdown.

What is implemented

About 215 native numbers (193 of them with a Linux number) covering:

Area
Process	fork, exec, exit, exit_group, wait/waitpid/wait4/waitid, clone (processes and threads), futex, kill, tgkill, sessions, process groups
Identity	the full real/effective/saved set for both uid and gid, groups, umask
Memory	mmap, munmap, mremap, mprotect, brk/sbrk, madvise, System V shared memory, memfd
Filesystem	the ordinary set, the whole *at() family, statfs, xattr, mount/umount2
I/O	read/write, readv/writev, pread/pwrite, sendfile, poll/select/ppoll/pselect6, epoll (create, create1, ctl, wait, pwait), ioctl, fcntl
Sockets	socket, bind, listen, accept/accept4, connect, sendto/recvfrom, sendmsg/recvmsg, socketpair, getsockname/getpeername, setsockopt/getsockopt, over AF_UNIX, AF_INET and AF_NETLINK
Signals	rt_sigaction, rt_sigreturn, rt_sigsuspend, rt_sigpending, rt_sigtimedwait, sigaltstack
Time	gettimeofday, clock_gettime, clock_getres, nanosleep, clock_nanosleep, alarm, timers
Notification	eventfd, timerfd, signalfd, inotify -- see kernel/sys/sys_event.c

Argument fetching

fetchint, fetchaddr, fetchstr and argptr validate a user pointer through the page tables and nothing else. They previously rejected any address >= proc->sz, on the assumption that every valid user pointer lives in the heap — which is wrong for stack addresses and for every mmap'd buffer, i.e. for most pointers real programs pass.

uva2ka() translates a user virtual address and returns the in-page offset, which it did not originally do. Every caller that read or wrote through a non-page-aligned pointer — TIOCGPGRP, TCGETS, getcwd, signal masks, times(), sysinfo() — was touching the wrong address whenever the pointer was not page-aligned, i.e. almost always.

uva2ka() guarantees only the page containing that address. A structure copied in bulk through one translation runs off the end of the mapped page when the pointer lands near a boundary — and P2V is a flat offset, so "the next page" in kernel space has nothing to do with the user's next page. That bug corrupted unrelated kernel memory and crashed every freshly exec'd shell. Copy field by field, each through its own translation, or use copyin/copyout.

---

What it does not do

• sendmsg/recvmsg carry SCM_RIGHTS and SCM_CREDENTIALS, and nothing else. Credentials are delivered only to a socket that asked with SO_PASSCRED (D-Bus and WebKit do); other control messages are refused rather than ignored. See networking.md.
• setsockopt applies the options it understands — they reach lwIP's pcb or the Unix socket — and answers ENOPROTOOPT for everything else, never a success that did nothing. The options that take a struct (SO_RCVTIMEO, SO_SNDTIMEO) are among the refused.
• sched_setaffinity is accepted and ignored.
• The ABI is chosen by link address. Anything linked at 0x100000 or above — musl's programs, and every dynamically linked one, whose interpreter is placed at 0x40000000 — gets the Linux map; a first-party program linked at 0x4000 gets the native one. It works, and it is a heuristic rather than a fact about the binary.
• ptrace and seccomp are not implemented; a program that needs them gets ENOSYS.