Kernel subsystems

The kernel connects scheduling, memory, storage, networking, and applications through shared syscall and causal-event interfaces. Each subsystem below includes its role, diagnostic commands, and implementation paths.

The native SMP chapter is current. Other command and source walkthroughs retain historical i386 implementation details, including graphics. Native acceptance identifies the qualified x86-64/AArch64 interfaces; this inventory does not imply every older subsystem has been ported.

Kernel visual atlas: memory, execution, SlFS, causal evidence, and network / actors.

Causal graphcjournalscrub/causalSlFSremote shell

From commands to implementation

Choose a command, observe its output, then follow the source files that explain the transition. The useful reading order is prompt, syscall or command handler, subsystem, causal event, and durable record.

Subsystem index

Roles and concepts for all 20 subsystems
ChapterSubsystemConcept
01Boot and CPU tablesNative machine entry and architecture-specific interrupt state
02Memory managerFrames, pages, per-task isolation, and the heap
03Scheduler and tasksPreemption, context frames, and userspace concurrency
04Syscall gateControlled entry from user code to kernel services
05Causal graph coreEvery important action becomes an event with parents
06Durable causal journalSearchable history on SlFS, beyond the hot ring
07Causal query toolingFilter, prove, save, and aggregate causal records
08Replay and time-travelReconstruct past state rather than trust a snapshot of now
09Counterfactual analysisAsk which effects depend on an event
10Web causal explorerA live SVG DAG and time-travel scrubber served by SlOS
11SlFS and storageBlock devices, directory state, and persistent files
12Networking and TCPFrames, address resolution, transport state, and services
13Remote terminal and shellsA remote workstation over telnet or a from-scratch encrypted channel
14Timelines and graph-native appsApplication state as named event chains
15Actors, mesh, and federationNamed endpoints and routed messages
16User programs and scriptingELF loading, runtime wrappers, slosh automation, games, and recovery tools
17Trust and non-repudiationSigned causal history another machine can verify
18Multi-core task dispatchDefault native SMP; preemptive AP-pinned kernel work with BSP-owned services
20Application workbench and recoveryGuest source editing with trusted host compilation
19High-resolution graphicsA 1024x768x32 framebuffer, additive over VGA text

Boot and CPU tables

x86-64 boots a GRUB ISO and enters long mode; AArch64/QEMU virt boots an ARM64 Image with a firmware device tree into EL1. Architecture entry establishes tables, stacks, interrupts and the HAL before native memory, devices and the user shell become available.

The x86-64 path uses its CPU tables and APIC; ARM uses exception vectors, GIC and architecture timers. A graphical host window or several online CPUs does not by itself establish application or multicore behaviour.

Diagnostic commands and source files 
make doctor
make dev
status
irqstat
events 5
  • arch/x86_64/boot.asm
  • arch/x86_64/interrupt.asm
  • arch/x86_64/hal.c
  • arch/aarch64/boot.S
  • arch/aarch64/vectors.S
  • arch/aarch64/boards/qemu_virt/hal.c

Memory manager

The PMM tracks physical frames. Each native user process owns its frames and private four-level translation tree, while the kernel identity window stays supervisor-only. Static ELF64 mappings start above 4 GiB; the fixed 1 MiB stack has an unmapped lower guard page, and the process heap is bounded.

Code is read-only; data, stack and heap are non-executable. User-pointer validation checks actual current mappings. Failed mapping growth rolls back new frames and tables; stacks do not automatically grow.

Diagnostic commands and source files 
free
memmap
heap test
  • kernel/core/memory.c
  • kernel/core/vmm.c
  • kernel/core/elf.c
  • kernel/core/task.c
  • include/memory.h
  • docs/ARCHITECTURE.md

Scheduler and tasks

Task records retain priority, lifecycle, parentage, blocked state and saved native context. The kernel preempts user processes and kernel tasks. Background launch and jobs, wait, fg and renice provide the shell's scoped process controls.

Native switching preserves architecture register and FP/SIMD state. User processes and general services stay on CPU 0, while explicitly AP-pinned service-free kernel work may run on other CPUs. Hew's in-process actor scheduler remains cooperative.

Diagnostic commands and source files 
ps
spawn httpd
worker 5 &
jobs
renice 1 6
  • kernel/core/task.c
  • kernel/core/syscall_process.c
  • arch/x86_64/context.asm
  • arch/aarch64/context.S
  • programs/shell.c
  • include/task.h

Syscall gate

Native x86-64 INT 0x80 and AArch64 SVC carry full-width syscall arguments into C dispatch. The LP64 SDK exposes files, streams, processes, metadata, networking and structured event interfaces without a hosted Linux ABI.

User pointers are checked against the current process mappings before use. Signal callbacks enter user mode and return through the kernel's saved context. Privileged operations need explicit capability rather than an executable-name exception.

Diagnostic commands and source files 
uname
ps
events 10
why <syscall-event-id>
  • kernel/core/syscall.c
  • kernel/core/syscall_dev.c
  • kernel/core/syscall_graph.c
  • kernel/core/syscall_net.c
  • include/syscall.h
  • lib/slos.h

Causal graph core

The causal graph assigns IDs, Lamport time, type, subsystem, description, hashes, and parent edges. Shell commands expose recent roots, traces, effects, paths, DOT output, and activity views.

Use the hot ring for immediate study, then switch to journal-backed commands when an event has aged out or crossed a reboot boundary.

Diagnostic commands and source files 
events 10
why last
trace <event-id>
blast <event-id>
cpath <ancestor-id> <event-id>
cdot <event-id>
ctop 128
  • kernel/graph/causal.c
  • kernel/apps/cmd_graph.c
  • programs/shell.c
  • include/causal.h

Durable causal journal

cjournal persists causal records to SlFS segments with indexes, retention controls, JSON/long forms, archived trace/effects/parents, and read-through used by why -a and trace -a.

Observe the source field in query output: hot rows come from ring; archived rows come from journal. Verify aged events with journal lookup, journal trace, and events -a.

Diagnostic commands and source files 
journal recent 10
events -a 10
events -a find syscall
why -a last
trace -a last
  • kernel/graph/cjournal.c
  • include/cjournal.h
  • programs/shell.c
  • kernel/fs/blockfs.c

Causal query tooling

The shell query layer supplies cq for hot and archived records, ctop for subsystem activity, cwatch for live causal tailing, why --md for Markdown export, lens for saved SlFS-backed queries, and shell filters for pipeline aggregation.

Prefer cq -a for durable history. Use cwatch or cwatch tail for a live graph stream; press any key to stop. The older builtin pipelines use bounded sequential capture. Current native all-external pipelines support up to four concurrent stages with binary input/output; mixed builtin/external composition is rejected.

Diagnostic commands and source files 
cq -a type=syscall limit=10
cq -a id=last epoch-proof --json-ish
why --md last
cwatch tail
lens save syscalls cq -a type=syscall limit=10
lens run syscalls
events | tail -n 5
ps | grep shell
journal type sched 50 | tally
  • programs/shell.c
  • kernel/graph/cjournal.c
  • kernel/graph/search.c
  • kernel/graph/integrity.c

Replay and time-travel

The replay engine walks causal history to reconstruct task, syscall, filesystem, network, and actor counts at a tick. The scrub program presents that reconstruction as a TUI and one-shot command set.

A reconstructed frame is a derived view. Compare scrub <tick>, scrub json <tick>, scrub diff, replay, and rewind before treating any current counter as permanent truth.

Diagnostic commands and source files 
scrub 100
scrub event last
scrub diff 100 999
scrub json 999
rewind 100
replay 100
  • kernel/graph/replay.c
  • include/replay.h
  • programs/scrub.c
  • kernel/graph/integrity.c
  • kernel/apps/cmd_graph.c

Counterfactual analysis

whatif walks downstream effects from an event and reports the impact of removing or changing that cause. scrub whatif exposes the same idea from the time-travel inspector.

Use counterfactuals on specific event IDs, not vague subsystems. The useful answer is the set of affected descendants and the verdict on system impact.

Diagnostic commands and source files 
whatif summary <event-id>
scrub whatif last
blast <event-id>
  • kernel/graph/whatif.c
  • programs/scrub.c
  • kernel/graph/causal.c

Web causal explorer

The ring-3 httpd program serves /causal, /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot over the SlOS TCP stack.

The page is not a screenshot. It fetches graph JSON, renders SVG nodes and edges, focuses ancestors/effects on click, and calls /api/causal/state?tick=N when the scrubber moves.

Diagnostic commands and source files 
httpd
# host side
curl http://localhost:8080/api/causal/graph
curl 'http://localhost:8080/api/causal/state?tick=100'
curl http://localhost:8080/api/causal/dot
  • programs/httpd.c
  • kernel/net/tcp.c
  • kernel/net/net.c
  • kernel/graph/replay.c
  • kernel/graph/causal.c

SlFS and storage

VirtIO block I/O supplies synchronous sector reads and writes. SlFS provides directories, files, metadata, block allocation, cache, fsck, and persistence for journals, lenses, snapshots, exports, and user files. The shell now presents a coherent overlay namespace: /tmp and relative paths are RAM scratch; other absolute paths such as /home/... persist to SlFS, with reads checking RAM first and SlFS second.

Distinguish completed I/O from durable publication. SlFS v2 has explicit redo recovery; legacy v1 is not silently converted. Failed or unsupported shutdown barriers refuse poweroff, and uncertain storage blocks later publication. Saved-project recovery replays only a new copy, leaving the original unchanged.

Diagnostic commands and source files 
mkdir /home/field
write /home/field/log.txt storage event
cat /home/field/log.txt
write /tmp/scratch.txt volatile
pwd
fsck
  • kernel/drivers/virtio.c
  • kernel/drivers/virtio_blk.c
  • kernel/fs/blockfs.c
  • kernel/fs/fs.c
  • kernel/apps/cmd_files.c
  • include/fs_route.h
  • include/blockfs.h

Networking and TCP

VirtIO net moves Ethernet frames. ARP, IPv4, UDP, DHCP, ICMP, TCP, wget, httpd, telnetd, chatd, netstat, and tcptrace expose the stack from packet to service. chatd is an IRC-lite multi-user TCP service on port 6667 with /nick, join/leave announcements, and broadcast across up to eight clients.

Check byte order at every boundary. TCP state transitions are the best compact evidence that the packet path is coherent. chatd is deliberately small: fixed eight-client table, CR/LF line buffering, and task-per-session workers rather than a general async server.

Diagnostic commands and source files 
dhcp status
ifconfig
arp
netstat
tcptrace
chatd start
chatd status
# host side: nc localhost 6667
wget 10.0.2.15 /api/sysinfo
  • kernel/drivers/virtio_net.c
  • kernel/net/net.c
  • kernel/net/dhcp.c
  • kernel/net/tcp.c
  • kernel/net/wget.c
  • programs/httpd.c

Remote terminal and shells

telnetd listens on guest port 23 (QEMU hostfwd localhost:2323) and noiseshd listens on 5200. Each accepted connection spawns a shell task with per-task I/O hooks, so console writes go back over TCP and shell/editor input comes from that session. The Noise shell performs an ephemeral X25519 exchange and then frames the byte stream with ChaCha20-Poly1305; it is confidential against passive listeners but currently unauthenticated, not OpenSSH.

Terminal redirection is the enabling layer: console clear, cursor, and colour emit ANSI through io_write; SYS_TERM_GETKEY decodes arrows, Ctrl-S/Ctrl-Q/Ctrl-C/Ctrl-L, and other cooked keys; SYS_CON_GETSIZE reads the session size populated by telnet NAWS. Long-lived daemons such as httpd, telnetd, and noiseshd detach from session I/O so they survive disconnect, while foreground editors remain session-owned.

Diagnostic commands and source files 
# host side, default QEMU forwarding
telnet localhost 2323
# or encrypted, from the SlOS repo
python3 scripts/noise-shell-client.py localhost 5200

# SlOS shell
termsize
edit /home/field/day.sl
run /home/field/day.sl
httpd
exit
# host side
curl http://localhost:8080/
  • docs/remote-access.md
  • kernel/apps/telnetd.c
  • kernel/core/syscall.c
  • kernel/drivers/console.c
  • programs/editor.c
  • scripts/noise-shell-client.py
  • kernel/core/task.c

Timelines and graph-native apps

Timelines give notes, mail, the editor, process views, and scheduled commands ordered event streams with rewind, forward, at, show, and replay operations.

The previous timeline head becomes the parent of the next event. Current app state is a replayed view of ordered payloads.

Diagnostic commands and source files 
note add timeline state is replayable
tl show notes
tl rewind notes 5
tl forward notes 5
mail
edit
scheduled
  • kernel/graph/timeline.c
  • kernel/apps/notes.c
  • kernel/apps/mail.c
  • kernel/apps/sched_app.c
  • include/timeline.h

Actors, mesh, and federation

Actors are named mailboxes. Routes, Noise-based mesh identity, and federation let selected messages and causal graph material move beyond the local actor table.

Trace actor registration, local delivery, dead-letter behaviour, remote proxy selection, peer identity, and federated causal edges.

Diagnostic commands and source files 
actors
send shell local loop
recv shell
mesh
routes
federation
why remote_parent shell
  • kernel/graph/actor.c
  • kernel/graph/mesh.c
  • kernel/graph/federation.c
  • kernel/core/noise.c
  • kernel/apps/cmd_graph.c

User programs and scripting

The program registry and ELF loader start shell, httpd, wget, browser, scrub, rogue, DOOM, and other ring-3 programs. The in-kernel slosh interpreter now has functions (func/end), $1..$9 positional parameters, return, bounded recursion, for loops, and shell-command passthrough, so scripts can drive ls, cat, wget, and other shell surfaces. Kernel commands also expose the surgeon crash shell for recovery exercises.

Separate kernel built-ins from user ELFs and scripts. slosh variables are global except saved positional parameters, recursion is bounded, and unknown slosh commands dispatch through shell_exec after expansion.

Diagnostic commands and source files 
write /home/fib.sl func countdown
  echo $1
  if $1 != 1
    expr n $1 - 1
    countdown $n
  end
end
countdown 3
run /home/fib.sl
exec browser about:slos
scrub help
rogue
doom
crash int3
  • kernel/core/elf.c
  • kernel/apps/script.c
  • docs/scripting.md
  • programs/shell.c
  • programs/browser.c
  • programs/rogue.c
  • programs/scrub.c
  • kernel/apps/cmd_apps.c

Trust and non-repudiation

A persistent per-node Ed25519 key signs each verified journal epoch root into a sidecar. Over the Noise-encrypted mesh a node distributes its public signing key and shares a signed segment root; a peer independently recomputes that root from imported events and verifies the signature, so cross-node causal history is non-repudiable. Refused roots raise per-peer rate-limited integrity events.

verify-sig recomputes the Merkle root from durable events before checking the signature, so tampering at any layer is caught. On-node verification proves self-consistency; authenticity needs the peer's distributed key — exactly what the cluster gate checks. Primitives (SHA-512, Ed25519, ChaCha20-Poly1305, BLAKE2s, Curve25519) are cross-validated against PyNaCl and OpenSSL.

Diagnostic commands and source files 
journal sign 1
journal verify-sig 1
journal trust-health
federation identity
federation share-root 1
  • kernel/core/noise.c
  • kernel/graph/cjournal.c
  • kernel/graph/federation.c
  • kernel/graph/mesh.c
  • include/federation.h

Multi-core task dispatch

Native x86-64 and AArch64/QEMU virt default to SMP=1 CPUS=4. x86-64 starts APs through INIT-SIPI-SIPI with per-CPU LAPIC timers; QEMU virt uses PSCI CPU_ON and per-CPU ARM timers. Shared priority queues and lifecycle transitions use an IRQ-saving scheduler lock. Explicitly AP-pinned, service-free kernel work is timer-preempted.

User processes, allocation, filesystems, networking and general services remain on CPU 0. Native automatic offload, migration and inter-core actor transport are not implemented. make smp-check proves overlapping execution, FP preservation, locking and remote task lifecycle alongside a real BSP user child; make smp-up-check covers UP debugging. The older i386 cooperative offload transcript is not this implementation.

Diagnostic commands and source files 
smp
cpus
smp test
  • kernel/core/native_smp.c
  • include/smp.h
  • include/spinlock.h
  • kernel/core/task.c
  • docs/smp.md

Application workbench and recovery

The develop client sends declared C or Hew sources to a trusted Linux worker, checks returned source and native ELF identities, and retains selected/previous builds and compiler feedback. The console launcher provisions an interactive session without driving application commands.

Diagnostics, current edits and installed code are different states. Rollback selects code without restoring source or application data. Rescue exports checked saved project files; fresh-copy recovery and explicit import start a new session, not unsafe original resume.

Diagnostic commands and source files 
exec /develop.elf status /home/demo
exec /develop.elf diagnostics /home/demo
exec /develop.elf edit /home/demo
  • programs/develop.c
  • programs/editor.c
  • scripts/development-worker.py
  • scripts/development-console.py
  • scripts/development-rescue.py
  • scripts/development-recover.py
  • scripts/development-import.py

High-resolution graphics

Beyond the 80x25 text console and DOOM's 320x200 mode, the gfx command switches to a 1024x768x32 linear framebuffer using QEMU std-VGA's Bochs VBE registers and the PCI-BAR framebuffer. gfxdash renders an interactive system dashboard; wm builds a keyboard-driven tiled desktop with live CPU, causal-tail, task-list, and memory/system panels.

It is purely additive: the high-res path keeps its own state, so the default text console and DOOM are untouched, and the whole thing is x86-only. wm is not a compositing desktop and has no mouse path yet; it redraws fixed tiled panels, cycles focus with Tab, and exits with q/Esc. Headless selftests use framebuffer readback to validate pixels without relying on a host display.

Diagnostic commands and source files 
gfx
gfxdash
wm
showcase
  • arch/x86/vga13h.c
  • include/gfx.h
  • kernel/apps/cmd_apps.c
  • kernel/drivers/fbcon.c
  • include/fb.h

Related material: guided trails, execution walks, causality, source, showcase, manual, and glossary.