These plates follow ordinary SlOS commands from prompt to device, program, or graph record.
Each walk gives the transcript, event path, source files, and the operating-system idea to
carry to the next bench session.
The notes command is a compact tour of SlOS state handling. One short line of text enters the command interpreter, receives causal context, becomes a timeline event, updates the durable notes snapshot, and can be exported as a plain SlFS file.
slos:/$ note add map the write path before changing it
Note #7 added.
slos:/$ note tag last manual
Tagged note #7 with manual
slos:/$ note export /exports/notes.txt
Exported notes to /exports/notes.txt
slos:/$ diskcat /exports/notes.txt
SlOS notes export
#7 T+22681 map the write path before changing it [manual]
slos:/$ trace 2388
2388 syscall BLOCKFS pid=31
<- 2387 notes tag note #7 manual
<- 2386 notes map the write path before changing it
What the reader learns
Timeline note procedure
Event-sourced application state: state is rebuilt from a named timeline, while snapshots and exports give the operator durable checkpoints.
Event path
Command entry
The operator types `note add`. Kernel shell argument parsing lands in `cmd_note()`, the same service reached by user programs through the shell-command syscall path.
Syscall context
`syscall_handler()` emits a `syscall` causal record for INT 0x80 calls and pushes it as current context, so child work can point back to the request.
Timeline append
`notes_add()` calls `timeline_emit(notes_tl, NOTE_ADD, ...)`. The previous notes head becomes the parent when one exists.
Causal event
`timeline_emit()` packages the payload and calls `causal_emit_payload()`. The graph now has an addressable note event with parent edges.
Snapshot and export
The notes module writes A/B snapshots through SlFS, then `note export` writes a readable file that can be copied, inspected, or imported later.
Source files
kernel/apps/notes.c
`cmd_note()`, `notes_add()`, snapshot save, export, import, and replay state.
kernel/graph/timeline.c
Named timeline creation, payload packing, head/cursor movement, and replay callbacks.
kernel/graph/causal.c
Event allocation, Lamport time, parent IDs, child counts, and query support.
kernel/core/syscall.c
INT 0x80 entry, syscall causal context, and dispatch to domain handlers.
The text browser shows how a registered ELF leaves the shell, receives an argv stack, reads a SlFS document, and prints rendered output through the syscall gate.
slos:/$ diskwrite /docs/boot.html "<h1>Boot notes</h1><p>Rendered by the browser ELF.</p>"
slos:/$ exec browser file:/docs/boot.html -find browser
[elf] loaded 'browser' (entry 0x8048000, pid 42)
SlOS Browser ELF: file:/docs/boot.html (33 bytes)
Matches:
Rendered by the browser ELF.
slos:/$ events 5
2410 shell exec: browser at 0x8048000
2411 syscall STAT pid=42
2412 syscall BLOCKFS pid=42
2413 syscall WRITE pid=42
2414 syscall EXIT pid=42
What the reader learns
User program procedure
Executable loading: program registry lookup, ELF segment mapping, user stack construction, task scheduling, and ordinary user I/O through syscalls.
Event path
Shell dispatch
`cmd_exec()` accepts a program name or a `/path.elf`. For `browser`, it uses `elf_find()` to select the embedded program image.
ELF load
`elf_load_args()` validates ELF32, allocates user pages for PT_LOAD segments, copies file bytes, and builds argc/argv near `USER_STACK_TOP`.
Task entry
The loader creates a user task, emits `exec: browser`, creates `proc/<pid>`, and marks the task ready for the scheduler.
Browser syscalls
`programs/browser.c` uses `SYS_STAT` and blockfs helper syscalls to read the document, then `SYS_WRITE` to send rendered text to the console.
Visible output
The browser output is plain terminal text. The operator can save it with `-o /path`, which returns to the SlFS write path.
Source files
kernel/apps/cmd_system.c
`cmd_exec()` dispatches embedded ELFs and disk-loaded ELF paths.
kernel/core/elf.c
ELF validation, segment loading, argv setup, task creation, and process timeline creation.
programs/browser.c
Document reader, HTML/text renderer, link listing, find mode, and output/save behaviour.
include/syscall.h
Syscall numbers for write, stat, blockfs, and process exit.
kernel/core/syscall_dev.c
Blockfs syscall sub-operations used by the browser.
A local HTTP request crosses the same network stack used for external packets: TCP state, IPv4 framing, Ethernet framing, VirtIO queues, receive polling, and a user-space HTTP handler.
Layering: device queues carry Ethernet frames; IP routes packets; TCP supplies connection state; the application receives a byte stream.
Event path
Server side
`cmd_httpd()` loads the HTTP server ELF. The program calls `tcp_listen(80)`, waits in `tcp_accept()`, and passes each connection to `handle_request()`.
Client connect
`wget_fetch()` calls `tcp_connect()`. TCP allocates a connection, emits a SYN_SENT causal root, and sends a SYN segment.
Frames on the wire
`tcp_xmit()` feeds `ip_send()`, which resolves ARP when needed, builds IPv4, calls `eth_send()`, and hands the frame to `net_send()`.
VirtIO network device
`virtio_net.c` wraps frames with the legacy VirtIO net header, pushes TX descriptors, kicks queue 1, and reposts RX buffers on queue 0.
Application reply
`net_stack_poll()` drains RX frames. TCP reassembles bytes; `httpd` reads `GET /api/sysinfo`, builds JSON, and writes an HTTP/1.0 response.
Source files
kernel/apps/cmd_net.c
`httpd`, `wget`, `netstat`, and `tcptrace` command entry points.
programs/httpd.c
User-space TCP listener and dashboard request handler.
kernel/net/wget.c
HTTP/1.0 client, TCP connect/send/receive, and optional SlFS save.
kernel/net/tcp.c
Connection pool, handshake, send/receive queues, retransmit logic, and causal TCP events.
Persistent filesystem mechanics: path resolution, inodes, direct and indirect data blocks, cached sectors, bitmap allocation, and synchronous block I/O.
Event path
Command buffer
`cmd_diskwrite()` normalizes the path, creates the file if needed, joins the text into a 512-byte command buffer, and calls `blockfs_write_file()`.
SlFS inode work
`blockfs_write_file()` reads the inode, emits an SlFS causal event, frees old blocks, allocates bitmap entries, and records direct or indirect sector numbers.
Sector write
Each file block is copied into a zeroed 512-byte sector buffer and sent through `blk_write()`. Successful writes update the small SlFS cache.
VirtIO block request
The block driver builds a descriptor chain: request header, data buffer, and status byte. It kicks queue 0 and polls for completion.
Operator check
`diskcat`, `diskstat`, `fsck`, and `diskcache` give the operator a direct view of the file and the backing store health.
Source files
kernel/apps/cmd_files.c
`diskwrite`, `diskappend`, file inspection, path handling, and SlFS commands.
kernel/fs/blockfs.c
SlFS superblock, bitmap, inode I/O, write/append paths, cache, and fsck.
kernel/drivers/virtio_blk.c
Synchronous VirtIO block read/write requests and retry/error records.
kernel/drivers/virtio.c
Legacy PCI virtqueue allocation, descriptor push/pop, and queue kick support.
include/blockfs.h
SlFS limits, inode structures, flags, and public API.
Walk 05
actor send -> mailbox -> causal actor event -> mesh/federation path
Actor delivery starts as a named send. Local targets receive a mailbox entry. Remote targets use the same name route, then federation packages the message for encrypted mesh transport.
slos:/$ actors
ID Name Type Node Msgs In Msgs Out Mailbox
1 dead-letter local - 0 0 0/16
2 shell local - 0 3 0/16
9 chat-peer remote 3b8a12c4 0 0 0/16
slos:/$ send shell local loop
Sent 10 bytes to 'shell'
slos:/$ recv shell
[type=1 from=2 t=30211] local loop
slos:/$ send chat-peer hello over mesh
Sent 15 bytes to 'chat-peer'
slos:/$ trace 2732
2732 actor recv name=shell type=1
<- 2731 actor send to=shell type=1 len=11
What the reader learns
Actor routing procedure
Message passing: explicit actor names, bounded mailboxes, causal send/receive edges, remote proxy actors, and cross-node graph material.
Event path
Name lookup
`cmd_send()` calls `actor_send_by_name()`. The actor routing table selects local targets first and falls back to remote proxies when needed.
Local mailbox
`actor_deliver_local()` writes a bounded mailbox slot, records sender identity, timestamp, payload length, and the causal event ID for the send.
Receive edge
`actor_recv()` removes the mailbox entry and emits a receive event whose parents include the current context and the send event.
Remote proxy
When the selected actor is marked remote, `actor_send()` calls `federation_send_actor()` with the peer node hash and original sender actor ID.
Mesh and federation
Federation attaches Lamport time and causal ID, then `mesh_send()` encrypts and frames the packet. The peer recv loop imports it and delivers to a local mailbox.
Source files
kernel/apps/cmd_graph.c
`actors`, `send`, `recv`, and graph inspection commands.
kernel/graph/actor.c
Actor registry, routes, local mailbox delivery, receive edges, and remote proxy dispatch.
kernel/graph/federation.c
Remote actor wire messages, registry sync, causal event federation, retry queue, and recv loop.
ChaCha20-Poly1305, BLAKE2s, and Curve25519 primitives used by the mesh.
Walk 06
DOOM launch -> user ELF/framebuffer path/showcase
The DOOM command exercises the loader, user syscalls, framebuffer abstraction, VGA mode 13h, keyboard polling, and optional frame capture used by the showcase clips.
slos:/$ doom
[elf] loaded 'doom' (entry 0x8048000, pid 52)
<screen enters 320x200 256-colour graphics mode>
<doomgeneric reads /doom2.wad and draws frames>
slos:/$ events 6
2810 shell exec: doom at 0x8048000
2811 syscall FB_INIT pid=52
2812 syscall FB_PALETTE pid=52
2813 syscall FB_BLIT pid=52
2814 syscall POLL_KEY pid=52
2815 syscall SLEEP pid=52
slos:/$ fbstream status
fbstream: capture available for mesh viewers and showcase recording
What the reader learns
Graphics showcase procedure
Device-facing user program: a ring-3 game drives palette, framebuffer blits, input polling, sleeps, and file access through the kernel boundary.
Event path
Launch
`cmd_doom()` looks up the `doom` ELF when the build includes DOOM support, starts it with `elf_load()`, and waits for the task to finish.
User program
`doom_entry.c` calls `doomgeneric_Create()` with `/doom2.wad`, then repeatedly calls `doomgeneric_Tick()` from user space.
Framebuffer syscalls
The platform layer issues `SYS_FB_INIT`, `SYS_FB_PALETTE`, and `SYS_FB_BLIT`, plus polling and sleep syscalls for keyboard and frame pacing.
VGA path
On x86, `fb_init()` enters mode 13h and `fb_blit()` copies the 320x200 indexed buffer to VGA memory. Palette changes use port I/O.
Showcase capture
`syscall_handle_dev()` also offers framebuffer capture to `fbstream`, giving mesh viewers and the website showcase a route to observe the running frame stream.
Source files
kernel/apps/cmd_apps.c
`cmd_doom()` ELF lookup, launch, wait loop, and build guidance when DOOM is absent.
kernel/core/elf.c
Shared ELF loader used by DOOM and other user programs.
doom/platform/doom_entry.c
User-space DOOM main entry and WAD argument setup.
doom/platform/doomgeneric_slos.c
SlOS platform glue for framebuffer, palette, input, serial keys, sleep, and ticks.
kernel/core/syscall_dev.c
Framebuffer syscall handler and fbstream capture hook.