Memory maps¶

This page covers both volatile memory (the SRAM layout the kernel lays out by hand) and the on-disk format of the EEPROM filesystem.

SRAM startup¶

The AVR does not clear RAM on reset, so the compiler emits a small crt0-style routine that zeroes the whole SRAM before @main runs. That makes a program start from the same controlled state on real silicon as it does in the simulator (whose RAM is already zero), so every global begins life at zero.

The SRAM map¶

kernel/memory.ik lays out SRAM by hand. The map is chosen to fit both the ATmega32 (RAM 0x0060–0x085F) and the ATmega328p (0x0100–0x08FF): kernel state sits at 0x0340 — above the compiler’s statics on either part — and process stacks fill up to 0x07FF, leaving 0x0800–RAMEND for the scheduler/reset stack on whichever device.

Range	Contents
`..0x033F`	compiler statics (ATmega32 from `0x0060`)
`0x0340..0x0565`	kernel state (zeroed at boot; `BSS_LEN = 0x0226`)
`0x0566..0x07FF`	process stacks (no overlap with kernel state)
`0x0800..RAMEND`	scheduler / reset stack

Kernel state¶

The kernel data region holds, in order: the process table (state, saved SP, and wake tick per pid), the ls tree renderer’s per-depth connector flags, the scheduler’s saved SP / current-pid / tick counter, the 26 script variables and the lazy bus-init and redirection flags, the shell’s line and expansion buffers, the two-slot mount table, the script/working scratch buffers, and the per-pid background-job state.

Symbol	Address	Role
`PROC_STATE`	`0x0340`	per-pid state byte
`PROC_SP`	`0x0344`	per-pid saved stack pointer
`PROC_WAKE`	`0x034C`	per-pid wake tick while sleeping
`TICKS`	`0x0364`	tick counter from the Timer0 ISR (`up`)
`VARS`	`0x0368`	the 26 script variables `a`–`z`
`CWD_LOC`	`0x039E`	working directory as a packed `(device, node)`
`LINE_BUF`	`0x03A0`	current input line (64 bytes)
`EXPAND`	`0x03E8`	line after `$var` expansion (80 bytes)
`MNT_*`	`0x0438`	two-slot mount table (used / device / mountpoint)
`SCRATCH`	`0x0440`	script-line / file working buffer
`BG_FILE`	`0x04E0`	per-pid background script location

Process stacks¶

Each process gets a fixed stack that grows downward; pid 0 (the shell) gets the most room. The three tile 0x0566–0x07FF with no gaps and no overlap with the kernel state below:

Process	Top	Size
pid 0	`0x07FF`	320 B
pid 1	`0x06BF`	160 B
pid 2	`0x061F`	186 B

The EEPROM filesystem layout¶

Each block device holds the same tree, but file data is allocated dynamically from a shared cluster pool (a FAT-style allocator), so a file grows to whatever free space allows instead of a fixed per-file slot.

A node is 16 bytes:

Bytes	Field
`[0]`	type (0 free, 1 file, 2 dir)
`[1]`	parent node index
`[2..3]`	length (u16)
`[4..11]`	name (8 bytes, NUL-padded)
`[12]`	first cluster (`0xFF` = empty file)

The internal volume (device 0) uses the whole 1 KB on-chip EEPROM, laid out as the node table, then the FAT (one next-pointer byte per cluster; 0xFF free, 0xFE end-of-chain), then the data clusters:

Range (in device)	Contents
`0x000..0x07F`	node table (8 nodes × 16 B)
`0x080..0x0B3`	FAT (52 cluster pointers)
`0x0B4..0x3F3`	data (52 clusters × 16 B) — files up to ~832 B

The external I2C EEPROM (device 2) uses 64 nodes with fixed 256-byte slots.

A packed location¶

A filesystem location is a 16-bit value device * 256 + node. CWD_LOC and the mount table store locations this way, so a path can name a node on any device and crossing a mount point is just following the location to a different device. The helpers @loc, @loc_dev, and @loc_node pack and unpack them.