Appendix G

Glossary and source atlas.

Use this page as a reading map. Each term gives the operating-system idea, the place it appears in SlOS, and the files to inspect next.

Manual Causality Source plates Showcase

Route

Manual

Boot order, command tables, subsystem inventory, and operating limits.

Route

Causality

Event records, Lamport time, parent edges, timelines, replay, and federation.

Route

Source plates

Annotated code excerpts for the causal graph, timelines, syscalls, actors, and notes.

Route

Showcase

Recorded runs of boot, SlFS persistence, user programs, timelines, actors, and DOOM.

Field terms

OS concepts in SlOS.

Term Explanation Where it appears Source files
GDT Global Descriptor Table: the x86 table that defines code, data, user, and TSS segment descriptors. Built during CPU table setup. The selectors are later used by kernel code, ring-3 entry frames, and the TSS descriptor.
  • include/x86.h
  • kernel/core/x86.c
  • arch/x86/boot.asm
  • kernel/core/task.c
IDT Interrupt Descriptor Table: the x86 dispatch table for exceptions, hardware IRQs, and software interrupts. Vectors 0-31 handle CPU exceptions, 32-47 receive remapped IRQs, and vector 128 receives INT 0x80 syscalls.
  • include/x86.h
  • include/interrupt.h
  • kernel/core/x86.c
  • arch/x86/interrupt.asm
  • kernel/core/interrupt.c
TSS Task State Segment: an x86 structure that supplies the ring-0 stack for privilege transitions. Installed in GDT slot 5. The scheduler updates esp0 before switching to a task that may enter the kernel from ring 3.
  • include/x86.h
  • kernel/core/x86.c
  • kernel/core/task.c
paging The x86 page-table mechanism that translates virtual addresses to physical frames with access flags. SlOS identity-maps the kernel region and maps user ELF segments, stacks, and process heaps with PTE_USER pages.
  • include/memory.h
  • kernel/core/memory.c
  • kernel/core/task.c
  • kernel/core/elf.c
PIT Programmable Interval Timer: the legacy timer that produces periodic interrupts. Configured at boot for the system tick. The timer handler wakes sleepers, decrements quanta, and can enter the scheduler.
  • include/interrupt.h
  • kernel/core/interrupt.c
  • kernel/core/task.c
PIC Programmable Interrupt Controller: the legacy interrupt controller that routes hardware IRQ lines to CPU vectors. Remapped so IRQ0 starts at interrupt 32. The IRQ handler sends end-of-interrupt signals before device handlers run.
  • include/interrupt.h
  • kernel/core/interrupt.c
  • include/x86.h
VirtIO A paravirtual device interface using PCI registers and virtqueues shared with the device model. PCI enumeration finds the devices. The common layer manages queues used by the block and network drivers.
  • include/virtio.h
  • kernel/drivers/pci.c
  • kernel/drivers/virtio.c
  • kernel/drivers/virtio_blk.c
  • kernel/drivers/virtio_net.c
ring 3 The x86 user privilege level used for SlOS user programs. User ELF tasks enter through an IRET frame with user selectors, private user mappings, and syscalls back through INT 0x80.
  • include/types.h
  • include/x86.h
  • kernel/core/x86.c
  • kernel/core/task.c
  • kernel/core/elf.c
  • kernel/core/syscall.c
syscall A controlled entry from a user program into kernel services. SlOS uses INT 0x80. EAX carries the syscall number; EBX, ECX, and EDX carry the first arguments.
  • include/syscall.h
  • kernel/core/syscall.c
  • kernel/core/syscall_graph.c
  • kernel/core/syscall_net.c
  • kernel/core/syscall_dev.c
  • arch/x86/interrupt.asm
ELF Executable and Linkable Format: the binary file format used for SlOS user programs. The loader validates ELF32 headers, maps PT_LOAD segments into a user task, prepares argv, and records an exec event.
  • include/elf.h
  • kernel/core/elf.c
  • programs/hello.c
  • programs/ringdemo.c
  • lib/slos.h
heap Dynamic memory reserved for runtime allocation. The kernel heap backs kmalloc and kfree. Ring-3 tasks receive a process heap that grows through SYS_SBRK.
  • include/memory.h
  • kernel/core/memory.c
  • kernel/core/task.c
  • kernel/core/syscall.c
SlFS SlOS File System: the persistent filesystem stored on the VirtIO block device. BlockFS manages superblocks, inodes, directory entries, block allocation, and filesystem syscalls.
  • include/blockfs.h
  • kernel/fs/blockfs.c
  • kernel/drivers/virtio_blk.c
  • kernel/core/syscall_dev.c
  • kernel/graph/timeline.c
TCP state The connection phase recorded by the TCP state machine, such as LISTEN, SYN_SENT, ESTABLISHED, and TIME_WAIT. Each tcp_conn tracks state, sequence numbers, retransmission data, receive buffers, and causal metadata.
  • include/tcp.h
  • kernel/net/tcp.c
  • kernel/net/net.c
  • kernel/core/syscall_net.c
Lamport clock A logical counter used to order causally related events. Every causal event receives Lamport time. Federation imports can merge remote Lamport values into the local clock.
  • include/causal.h
  • kernel/graph/causal.c
  • include/federation.h
  • kernel/graph/federation.c
causal DAG A directed acyclic graph of events connected by parent-to-child cause edges. Scheduler, syscall, filesystem, network, actor, mesh, and application operations can emit events with parent IDs.
  • include/causal.h
  • kernel/graph/causal.c
  • kernel/core/syscall.c
  • kernel/apps/cmd_graph.c
replay Reconstruction of state by walking recorded events up to a chosen tick or cursor. The replay engine reconstructs system snapshots; timelines replay application events to rebuild notes, mail, editor, and scheduler state.
  • include/replay.h
  • kernel/graph/replay.c
  • include/timeline.h
  • kernel/graph/timeline.c
actor mailbox A bounded message queue attached to a named actor. Actors register names, send typed payloads, receive from their mailbox, and keep causal information for local or remote delivery.
  • include/actor.h
  • kernel/graph/actor.c
  • kernel/core/syscall_graph.c
  • kernel/apps/mail.c
mesh federation The peer layer that carries actor delivery and causal event material between SlOS nodes. Mesh handles identity, discovery, handshakes, and encrypted channels. Federation serializes actor messages and causal graph updates.
  • include/mesh.h
  • kernel/graph/mesh.c
  • include/federation.h
  • kernel/graph/federation.c
  • kernel/core/noise.c
timeline cursor The current position inside a named application event chain. Timeline rewind and forward commands move the cursor. Replay walks events from creation to the cursor to rebuild application state.
  • include/timeline.h
  • kernel/graph/timeline.c
  • kernel/apps/notes.c
  • kernel/apps/mail.c
  • programs/editor.c
  • kernel/apps/sched_app.c

Source atlas

Important files by subsystem.

Boot and CPU tables

arch/x86/boot.asm Multiboot entry, early stack setup, descriptor-table flush helpers, and the jump into kernel_main().
kernel/core/main.c Subsystem initialization order for memory, CPU tables, drivers, networking, graph services, and applications.
kernel/core/x86.c GDT, IDT, and TSS construction for 32-bit x86.
arch/x86/interrupt.asm Uniform ISR, IRQ, and syscall stubs that build the registers_t frame.
kernel/core/interrupt.c PIC/PIT setup, IRQ dispatch, exception dispatch, and timer-driven scheduling hooks.

Memory, tasks, and user programs

kernel/core/memory.c Physical frame bitmap, kernel page tables, user page directories, and kernel heap allocator.
kernel/core/task.c Task pool, ready queues, context switching, ring-3 entry, signals, waits, and scheduler accounting.
arch/x86/context.asm Low-level stack switch for callee-saved registers and flags.
kernel/core/elf.c ELF32 validation, segment loading, argv setup, and user-task creation.
kernel/core/syscall.c INT 0x80 ABI, core syscall dispatch, user pointer checks, and process heap growth.

Storage and filesystems

kernel/fs/fs.c RAM filesystem tree used for early and transient files.
kernel/fs/blockfs.c SlFS superblock, inodes, block allocation, cache stats, fsck, and path operations.
kernel/drivers/virtio_blk.c Synchronous sector reads and writes over a VirtIO block queue.
kernel/core/syscall_dev.c Device-facing syscalls, including BlockFS sub-operations and framebuffer calls.

Network stack

kernel/drivers/pci.c PCI configuration-space scanning and BAR discovery for VirtIO devices.
kernel/drivers/virtio.c Legacy VirtIO PCI negotiation, virtqueue allocation, push, pop, and notify operations.
kernel/drivers/virtio_net.c Ethernet frame transmit and receive buffers for the VirtIO network card.
kernel/net/net.c Ethernet, ARP, IPv4, UDP, and packet dispatch into higher protocols.
kernel/net/tcp.c TCP connection table, state machine, send/receive buffers, retransmission, and diagnostics.
kernel/net/dhcp.c DHCP discover, request, and lease configuration for QEMU user networking.

Causality, replay, and timelines

kernel/graph/causal.c Causal event ring, Lamport time, parent links, query functions, and health metrics.
kernel/graph/replay.c Snapshot reconstruction and diffs from recorded causal events.
kernel/graph/timeline.c Named event chains, cursor movement, replay callbacks, persistence, and exports.
kernel/graph/causal_persist.c Persistence support for causal graph metadata.
kernel/apps/cmd_graph.c Shell commands for events, why, trace, graph views, replay, and timeline inspection.

Actors, mesh, and federation

kernel/graph/actor.c Actor registry, mailboxes, routes, supervision, remote actor proxies, and topology stats.
kernel/graph/mesh.c Peer discovery, SPIFFE identity, encrypted transport, heartbeat, and local peer registration.
kernel/graph/federation.c Remote actor delivery, causal event import/export, retries, and peer lifecycle hooks.
kernel/core/noise.c Cryptographic primitives used by the mesh transport.
kernel/core/syscall_graph.c User syscall surface for actors, mesh info, causal queries, timelines, and pub/sub.

Applications and operator surface

kernel/apps/shell.c Interactive command loop and command routing for kernel tools.
kernel/apps/notes.c Timeline-backed notes with search, tags, import, export, and snapshots.
kernel/apps/mail.c Timeline-backed mailbox using actor delivery events.
programs/editor.c Full-screen text editor, a user-space port of the graph-native editor.
kernel/apps/sched_app.c Timeline-backed scheduling of shell commands at future ticks.
programs/hello.c Small ring-3 program showing printf, getpid, and gettime through the user library.
programs/ringdemo.c Ring-3 protection demo that exercises ordinary syscalls and privileged-instruction faults.
lib/slos.h User-space syscall wrappers, types, and small C library declarations.

Reading order

A short route through the tree.

Start at kernel/core/main.c, then read the CPU table files, memory and task code, the syscall path, and the device drivers. After that, follow one concrete data path: SlFS file write, TCP packet, actor send, or timeline event. The causality page explains the event model used by those paths.