SlOS operating manual / web edition

A kernel that keeps the chain of cause.

SlOS is a bare-metal operating system organized around a causal graph. Every significant operation records what happened, when it happened, and which prior events gave it cause.

Start learning route Read the manual Watch the showcase Inspect source

General description

It is an operating system textbook made executable.

SlOS implements the familiar pieces -- boot, interrupts, memory, tasks, syscalls, storage, networking -- and binds them into one inspectable history. Its operating surface reads like a small 1980s workstation manual while it demonstrates event sourcing, actor routing, federation, and time-travel state.

Learning routes

Start with an observable command.

These pages are arranged for study. Choose one route, run the listed command in SlOS, then read the source path and event record that explain the result.

Route Use
Guided concept trails Short routes through boot, syscalls, TCP, timelines, and actors.
Subsystem chapters Per-subsystem role, source path, command, and learner watch points.
Execution walks Prompt-to-device traces for notes, ELF loading, HTTP, SlFS, actors, and DOOM.
Operator labs Hands-on QEMU exercises with expected observations and cleanup notes.
Glossary and source atlas OS terms paired with the SlOS files that implement them.
Showcase notes Video chapter prompts mapped to commands, subsystems, and source files.
Reading room Research lineage: logical clocks, event sourcing, provenance, actors, and limits.
Field manual Continuous printable reading order for the web manual.

01 / Kernel

A freestanding x86-32 machine

Multiboot starts the kernel at 1 MB. SlOS brings up GDT, IDT, paging, heap, PIC/PIT, VirtIO block and net, TCP/IP, SlFS, and ring-3 user programs from its own freestanding runtime.

02 / Causality

The system records why

Scheduler switches, syscalls, filesystem operations, actor messages, network packets, and app events become nodes in a causal DAG with Lamport time and parent edges.

03 / Timelines

Applications are event chains

Notes, mail, editor, and the scheduler store changes as timeline events. Rewind, forward, export, and replay use the same event representation.

04 / Federation

Actors travel over a mesh

Named actors use mailboxes locally and can be routed over a Noise-style mesh. The same graph model is intended to scale from QEMU peers to future per-core message passing.

System plate A

Boot sequence

GRUB loads the Multiboot image. Assembly sets the first stack and calls kernel_main(). The kernel installs tables, starts paging, builds a heap, mounts filesystems, initializes PCI and VirtIO, registers user ELFs, and starts the preemptive scheduler.

Target i686, QEMU, VirtIO
Memory 128 MB identity map; 96 MB heap
Causal ring 16,384 live events
Timelines 64 named chains
Actors mailbox routes plus dead-letter actor
Interface INT 0x80 syscalls and shell commands

System plate B

Causal map

shell command
->
syscall event
->
filesystem or network event
actor send
->
mailbox delivery
->
federated causal edge
timeline event
->
replay
->
current state

Demonstration transcript

A note becomes a graph path.

The shell command is a causal entry point. It creates a syscall event. The notes application emits timeline events. The timeline head becomes the next parent, making the note history replayable and explainable. 

slos:/$ note add audience asked about causality
Note #6 added.
slos:/$ note tag last demo
slos:/$ tl mark notes demo-checkpoint
slos:/$ tl tail notes -n 4
#1835 timeline notes: note added
#1836 timeline notes: tag attached
#1837 timeline notes: mark demo-checkpoint
#1838 syscall causal pid=31
Listing 1 kernel/graph/causal.c 
uint32_t causal_emit_payload(causal_type_t type,
                             const char *subsystem,
                             const char *desc,
                             const uint32_t *parent_ids,
                             int num_parents,
                             const void *payload,
                             uint32_t payload_len)
{
    lamport_clock++;
    uint32_t id  = next_id++;
    uint32_t idx = ring_index(id);

    causal_event_t *ev = &events[idx];
    memset(ev, 0, sizeof(*ev));
    ev->id   = id;
    ev->time = causal_now();
    ev->type = type;
    /* parent IDs turn ordinary activity into a navigable DAG */
}
Listing 2 kernel/graph/timeline.c 
uint32_t timeline_emit(int tl_id, uint32_t sub_type,
                       const void *data, uint32_t len,
                       const char *desc)
{
    /* payload: {tl_id, sub_type, data_len, data[]} */
    uint32_t parents[1];
    int nparents = 0;
    if (tl->head_id != 0) {
        parents[0] = tl->head_id;
        nparents = 1;
    }
    return causal_emit_payload(CAUSAL_USER, tl->app, desc,
        nparents ? parents : NULL, nparents, payload, plen);
}
SlOS booting in QEMU
Plate I: boot and services
SlOS causal and timeline demonstration
Plate II: causal/timeline operation
SlOS distributed DOOM showcase
Plate III: distributed DOOM showcase

Operator quick start

Build and enter the machine.

git clone https://github.com/slepp/slos.git
cd slos
make
make run-nographic

Field commands

Ask the system for its history.

events 10
why <event-id>
trace <event-id>
graph
tl show notes
tl rewind notes 20
actors
mesh