Manual section L

Guided concept trails.

Guided trails are small operator routes through SlOS concepts. Each route begins with a visible command, identifies what to observe, and points to the source files that perform the work.

Use of this page

Read by operating.

Boot the kernel, keep the source tree open, and follow one trail at a time. Each trail pairs a command to run, the output to watch for, the source files that perform the work, and a concept to carry forward.

Field setup

Keep the machine visible.

host$ make
host$ make run-nographic
slos:/$ events 10
slos:/$ graph-health

Trail 01

Boot to shell

Follow the machine from the Multiboot handoff to the first operator prompt. This is the base route for reading the rest of the system.

MultibootGDTIDTtaskingshell

Commands to run

host$ make
host$ make run-nographic
slos:/$ help
slos:/$ status
slos:/$ events 10

What to observe

1 The serial log names subsystems in dependency order as the kernel initializes.
2 The prompt appears after console, memory, interrupt, task, filesystem, and device setup have a usable base.
3 The recent event list contains shell activity and task context after entry.
Source files Boot to shell
arch/x86/boot.asm Multiboot header, stack setup, and the transfer into C.
kernel/core/main.c Subsystem ordering and the point where the shell becomes reachable.
kernel/core/x86.c Descriptor tables, TSS setup, and CPU-facing structures.
kernel/core/interrupt.c PIC, PIT, interrupt dispatch, and timer entry.
kernel/apps/shell.c The command table and operator loop.

Concept learned

Boot to shell

Boot is ordered construction. Each facility supplies footing for the next one: a console for diagnosis, tables for protected execution, memory for allocation, interrupts for time, tasks for scheduling, and the shell for operation.

Trail 02

Syscall crosses rings

Run a small user program and watch a software interrupt carry a request into the kernel. The trail shows where privilege changes become ordinary C dispatch.

ring 3INT 0x80register framereturn path

Commands to run

slos:/$ ringdemo
slos:/$ strace hello
slos:/$ events 12
slos:/$ trace <syscall-event-id>

What to observe

1 The user program prints from ring 3, then asks the kernel for service through a syscall.
2 The trace output names syscall numbers and the process that issued them.
3 The causal trace places the syscall below the task that caused it.
Source files Syscall crosses rings
programs/ringdemo.c A small user program that exercises the ring boundary.
programs/hello.c A minimal user program used by strace.
arch/x86/interrupt.asm Uniform interrupt frame construction before C dispatch.
kernel/core/syscall.c Syscall table, argument extraction, and return values.
include/syscall.h Syscall numbers and public interface constants.
kernel/core/task.c Task state, privilege frame setup, and scheduling context.

Concept learned

Syscall crosses rings

A syscall is a controlled crossing. The CPU enters a kernel gate, the assembly stub preserves the frame, C code reads the syscall number and arguments, and the task resumes with a result in the expected register.

Trail 03

Packet becomes TCP data

Start the HTTP server, send one host request through QEMU, and inspect the TCP events that remain. This trail treats the network stack as a sequence of small translations.

VirtIOEthernetIPv4TCPHTTP

Commands to run

slos:/$ ifconfig
slos:/$ httpd
host$ curl http://localhost:8080/
slos:/$ tcptrace
slos:/$ events 20

What to observe

1 ifconfig reports the QEMU user-network lease and the VirtIO MAC address.
2 The HTTP server prints its SlOS address and the host-forwarded URL.
3 tcptrace lists TCP causal events for connection setup, data movement, and close handling.
Source files Packet becomes TCP data
kernel/drivers/virtio_net.c Receive buffers, transmit buffers, and device interrupts.
kernel/net/net.c Ethernet, ARP, IPv4, UDP dispatch, and packet classification.
kernel/net/tcp.c Connection state, sequence numbers, acknowledgements, and payload delivery.
kernel/net/dhcp.c Lease acquisition used by the QEMU network route.
programs/httpd.c User-facing HTTP service that consumes TCP data.

Concept learned

Packet becomes TCP data

Network input becomes application data by losing one wrapper at a time. The device supplies a frame, Ethernet names the next protocol, IPv4 names the transport, TCP orders bytes, and the HTTP task reads a stream.

Trail 04

Note becomes timeline

Create a note, tag it, and inspect the timeline that records the operation. This is a compact route from an application command to replayable state.

notestimelinecausal eventreplay

Commands to run

slos:/$ note add field log begins at the prompt
slos:/$ note tag last boot
slos:/$ note list
slos:/$ tl show notes
slos:/$ why <note-event-id>

What to observe

1 The note command returns a stable note number for later operations.
2 The notes timeline records insertion and tag events in order.
3 The why command shows the immediate parents that made the note event possible.
Source files Note becomes timeline
kernel/apps/notes.c Note commands, import/export, snapshots, and replay application code.
kernel/graph/timeline.c Named event chains, cursors, marks, and replay traversal.
kernel/graph/causal.c Event allocation, parent links, and recent graph queries.
include/notes.h Notes interface presented to the rest of the kernel.
include/timeline.h Timeline names, event sub-types, and callback shape.

Concept learned

Note becomes timeline

An application fact is stored as an event with ancestry. Current note state is a convenient view; the timeline is the ordered material from which that view can be reconstructed.

Trail 05

Actor message crosses mesh

Run two SlOS nodes, join a chat actor on one node, and send a message from the other. The route shows local actor delivery and the mesh extension that carries the same idea between peers.

actormailboxroutemeshfederation

Commands to run

node-b slos:/$ chat depot
node-a slos:/$ meshview
node-a slos:/$ routes
node-a slos:/$ chat field hello over the mesh
node-a slos:/$ federation
node-a slos:/$ events 20

What to observe

1 meshview reports discovered or connected peers and their transport state.
2 routes shows actor names, route policy, and local or remote targets.
3 The chat actor receives a mailbox message; federation counters and causal events advance with delivery activity.
Source files Actor message crosses mesh
kernel/graph/actor.c Actor slots, route targets, mailbox send, receive, and dead-letter handling.
kernel/graph/mesh.c Peer discovery, identity, encrypted channel state, and transport framing.
kernel/graph/federation.c Remote actor delivery and causal graph exchange.
kernel/apps/cmd_graph.c actors, send, recv, chat, routes, and federation commands.
kernel/apps/meshview.c Operator display for mesh peers and channel state.
include/actor.h Actor records, route records, and message format.

Concept learned

Actor message crosses mesh

Actor delivery names communication explicitly. A sender places bytes in a typed message, the route table selects a target, local mailboxes or mesh transport carry the payload, and federation records the movement as causal history.

Operating rule: stop after each trail and identify the boundary that moved. Boot moves from loader to kernel. Syscalls move from user task to kernel service. Packets move from device frame to byte stream. Notes move from command text to timeline event. Actor messages move from one mailbox to another, with mesh carrying the same record between peers.