Field manual / subsystem chapters

Subsystem chapters.

Read SlOS as a set of operating-system instruments. Each chapter names the role of one subsystem, points at the source, and gives a command that turns the idea into a visible machine action.

Boot Memory Scheduler Syscalls TCP Timelines

Reading method

Trace one path at a time.

Choose a command, observe its output, then follow the source path that explains the observed transition. A useful reading session moves from operator command to syscall, kernel service, causal event, and visible state.

Route map

Ten subsystems to inspect.

Chapter Subsystem Concept
01 Boot and CPU tables Machine entry and protected-mode structure
02 Memory manager Frames, pages, heap, and allocation discipline
03 Scheduler and tasks Runnable state, timer preemption, and context switch frames
04 Syscall gate Controlled entry from user code to kernel services
05 SlFS and storage Block devices, directory state, and persistent files
06 Networking and TCP Frames, address resolution, transport state, and services
07 Actors and mesh Named endpoints and routed messages
08 Timelines and replay Application state as named event chains
09 User programs ELF loading, ring 3 execution, and runtime wrappers
10 DOOM A graphical user program exercising many subsystems together

Chapter 01

Boot and CPU tables

Role GRUB loads the Multiboot image, assembly creates the first stack, and kernel_main() initializes CPU tables, interrupts, devices, filesystems, and the first runnable tasks in dependency order.
Learner watch Follow the handoff from assembly to C, the placement of GDT/IDT/TSS records, the PIC/PIT interrupt path, and the point where timer interrupts begin driving the rest of the machine.
Source files arch/x86/boot.asm; arch/x86/interrupt.asm; kernel/core/main.c; kernel/core/x86.c; include/x86.h; include/interrupt.h

Learning target

Machine entry and protected-mode structure

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

make ARCH=x86 run-nographic
status
irqstat
events 5

Chapter 02

Memory manager

Role The physical memory manager tracks frames, the virtual memory manager installs the early identity map, and the heap gives kernel subsystems bounded dynamic allocation.
Learner watch Separate frame ownership from heap ownership. Check alignment rules, page-table writes, allocation metadata, and the moment a user program receives heap space through sbrk.
Source files kernel/core/memory.c; include/memory.h; kernel/core/syscall.c; lib/slos.h

Learning target

Frames, pages, heap, and allocation discipline

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

free
memmap
heap
memtrace

Chapter 03

Scheduler and tasks

Role The task system owns process slots, priorities, sleep state, parentage, and the transition between running contexts. The PIT timer supplies preemption; voluntary yield and blocking calls shape cooperative moments.
Learner watch Read the saved register set in context.asm beside the task structure. Trace a new task stack, then trace an existing task as it moves through ready, running, blocked, zombie, and dead states.
Source files kernel/core/task.c; arch/x86/context.asm; kernel/core/interrupt.c; include/task.h

Learning target

Runnable state, timer preemption, and context switch frames

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

ps
top
schedule 100 status
scheduled
proc

Chapter 04

Syscall gate

Role INT 0x80 moves user programs into the kernel with a syscall number and register arguments. The dispatcher records causal context and routes work to process, file, device, graph, network, and timeline handlers.
Learner watch Compare syscall numbers in include/syscall.h with wrappers in lib/slos.h. Watch which calls become causal events, which return errors, and how user pointers cross the privilege boundary.
Source files 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; lib/crt0.S

Learning target

Controlled entry from user code to kernel services

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

strace hello
ringdemo
events 10
why <syscall-event-id>

Chapter 05

SlFS and storage

Role VirtIO block I/O supplies sector reads and writes. SlFS builds directories, files, metadata, block allocation, and repair checks over that device while the RAM filesystem remains useful for volatile kernel files.
Learner watch Distinguish RAM filesystem paths from disk commands. Follow sector-sized transfers into SlFS blocks, then check inode updates, cache state, read-only flags, and fsck repair paths.
Source files kernel/drivers/virtio.c; kernel/drivers/virtio_blk.c; kernel/fs/blockfs.c; kernel/fs/fs.c; include/blockfs.h; include/fs.h

Learning target

Block devices, directory state, and persistent files

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

diskwrite /field.txt storage event
diskcat /field.txt
diskstat /field.txt
fsck

Chapter 06

Networking and TCP

Role The VirtIO network driver moves Ethernet frames. The stack handles ARP, IPv4, UDP, DHCP, ICMP, TCP connections, HTTP fetches, and shell-visible network diagnostics.
Learner watch Check byte order at every header boundary. Follow a received frame through ARP or IP dispatch, then through TCP sequence numbers, acknowledgements, retransmission state, and socket lifecycle.
Source files kernel/drivers/virtio_net.c; kernel/net/net.c; kernel/net/dhcp.c; kernel/net/tcp.c; kernel/net/wget.c; kernel/apps/cmd_net.c; programs/httpd.c

Learning target

Frames, address resolution, transport state, and services

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

dhcp status
ifconfig
arp
netstat
tcptrace

Chapter 07

Actors and mesh

Role Actors provide named mailboxes inside the kernel. Routes, federation, Noise-based mesh identity, and peer state let selected actor messages move beyond the local mailbox table.
Learner watch Trace actor registration before message send. Observe local delivery, dead-letter behaviour, route-table lookup, remote peer metadata, and causal events attached to message movement.
Source files kernel/graph/actor.c; kernel/graph/mesh.c; kernel/graph/federation.c; kernel/core/noise.c; include/actor.h; include/mesh.h; include/federation.h

Learning target

Named endpoints and routed messages

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

actors
routes
send log 1 hello
recv
mesh
federation

Chapter 08

Timelines and replay

Role A timeline is a named chain inside the causal graph. Applications append typed payloads, move a cursor through prior events, and reconstruct current state by replaying events up to that cursor.
Learner watch Watch the previous head become the parent of the next event. Separate recent causal history from durable snapshots, and inspect how note, mail, editor, and scheduler payloads encode state changes.
Source files kernel/graph/causal.c; kernel/graph/timeline.c; kernel/graph/replay.c; kernel/apps/notes.c; kernel/apps/mail.c; kernel/apps/sched_app.c; include/timeline.h

Learning target

Application state as named event chains

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

note add timeline state is replayable
tl show notes
tl mark notes checkpoint
tl rewind notes 5
tl forward notes 5

Chapter 09

User programs

Role The ELF loader installs user program segments, prepares a task, and starts execution with a small C runtime. Programs communicate with the kernel through syscall wrappers and receive process services from the scheduler.
Learner watch Inspect executable headers, load addresses, initial stack layout, heap limits, exit flow, and the way a user program appears in ps, strace, events, and process timelines.
Source files kernel/core/elf.c; include/elf.h; lib/crt0.S; lib/slos.h; programs/hello.c; programs/shell.c; programs/editor.c; programs/showcase.c

Learning target

ELF loading, ring 3 execution, and runtime wrappers

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

exec hello
exec neofetch
exec shell
strace editor

Chapter 10

DOOM

Role The DOOM port runs as a user program with framebuffer, palette, input, timing, file, and memory services supplied by SlOS. It is a compact integration test for the graphical syscall path and user runtime.
Learner watch Follow palette setup, frame blits, keyboard polling, WAD placement, and heap pressure. The useful lesson is the boundary between game code, porting shims, and kernel-provided devices.
Source files kernel/apps/cmd_apps.c; include/doom.h; doom/platform/doom_entry.c; doom/platform/doomgeneric_slos.c; doom/platform/doom_libc.c; arch/x86/vga13h.c

Learning target

A graphical user program exercising many subsystems together

Use the source files as the static map and the command transcript as the dynamic view. The useful question is which data structure changes when the command runs. 

scripts/setup-doom.sh
make ARCH=x86 DOOM=1
# in the SlOS shell
doom

Field note: subsystem study works by reading the command, the source file, and the event log together. A shell action gives the operator output; the source gives the mechanism; the causal graph gives the ordered record.