VIOS uses fixed-size tables and arenas everywhere: nothing is allocated
dynamically, so every capacity below is a compile-time constant. When a
limit is reached the operation fails with a message and the system carries
on. Each value is given with the source file that defines it (paths are
relative to the repository root; firmware/ means
firmware/esp32-vios/).
Forth system
| Item | Value | Source |
|---|---|---|
| Cell size | 24 bits (3 bytes), little-endian | include/forth/vm.h (FVM_MASK) |
| Signed / unsigned cell range | -8388608..8388607 / 0..16777215 | include/forth/vm.h |
| Dictionary entries | 512 | include/vios/config.h (VIOS_FORTH_WORDS_MAX) |
| Name pool | 5120 bytes | forth/system.c (VIOS_FORTH_NAME_BYTES) |
| Dictionary hash buckets | 128 | include/vios/config.h |
| Word name length | 1..31 characters | forth/system.c (NAME_MAX) |
| Token code arena | 16384 bytes | forth/system.c (TOKEN_BYTES) |
| Direct-threaded code arena | 32768 bytes | forth/system.c (DIRECT_BYTES) |
Data space (variables, CREATE, strings) |
8192 bytes | forth/system.c (DATA_BYTES) |
Source arena (text kept for SEE) |
8192 bytes | forth/system.c (SOURCE_BYTES) |
Source-map entries (TRACE/LAST-ERROR tokens) |
1792 | forth/system.c (SOURCE_MAP_MAX) |
| Native services | 150 | forth/system.c (NATIVES_MAX) |
| Data stack | 256 cells | include/forth/vm.h (FVM_DS) |
| Return stack | 256 cells | include/forth/vm.h (FVM_RS) |
| Loop stack | 32 frames | include/forth/vm.h (FVM_LOOPS) |
| Open control structures while compiling | 64 | forth/system.c (CONTROL_MAX) |
Pending LEAVE / ?DO exits per definition |
16 | forth/system.c (LEAVES_MAX) |
| Instructions per interactive command | 1,000,000 | forth/system.c (execute_index) |
TRACE step limit |
1..100000 | forth/system.c |
LAST-ERROR capture |
top 8 data cells, 16 caller frames | forth/system.c (CRASH_DS, CRASH_RS) |
| Error message length | 95 characters | forth/system.c (error_text) |
FILL / MOVE chunk (preemption point) |
256 bytes | forth/system.c (MEM_CHUNK) |
BASE range |
2..36 | forth/system.c |
| Words defined at boot | about 250 | RESOURCES on a fresh system |
Console and input
| Item | Value | Source |
|---|---|---|
| REPL input line | 255 characters | forth/system.c (forth_repl, 256-byte buffer) |
| ESP line editor line | 235 characters | firmware/include/vios_line.h (LENGTH) |
| Line history | 4 lines | firmware/include/vios_line.h (HISTORY) |
| Console screen | 80 columns x 58 rows + 1 status row | firmware/include/vios_console.h |
| Cursor blink | 500 ms | firmware/include/vios_console.h |
| Console-task output held until idle | 500 ms | forth/system.c (forth_repl) |
| CPU console output buffer | 128 bytes per flush | boards/agon-light-2/platform_resident.c |
| CPU console input ring | 512 bytes | include/drivers/vdp_transport.h |
| CPU key-event queue (routed keys) | 32 events | include/drivers/vdp_transport.h |
| UART receive ring (interrupt-driven) | 256 bytes, RTS dropped at 192 | boards/agon-light-2/platform_resident.c |
| Ctrl+C check while a command runs | every 50 ms | forth/system.c (PREEMPT_INTERRUPT_MS) |
Tasks
| Item | Value | Source |
|---|---|---|
| Background tasks | 4 | include/forth/system.h (FORTH_TASKS_MAX) |
| Task data / return stack | 64 / 64 cells | include/forth/system.h |
| Task loop stack | 16 frames | include/forth/system.h |
| Task output ring | 128 bytes | include/forth/system.h (FORTH_TASK_OUT) |
Instructions per slice (TASK-SLICE) |
default 1024, range 64..65535 | include/forth/system.h, forth/system.c |
| Preemptive slice / foreground quantum | 4 ms / 4 ms | forth/system.c (PREEMPT_SLICE_MS, PREEMPT_QUANTUM_MS) |
| Task error text | 47 characters | forth/system.c (struct task) |
CRITICAL( nesting |
255 | forth/system.c |
Modules, files and handles
| Item | Value | Source |
|---|---|---|
| Active modules | 8 | include/forth/modules.h (FORTH_MODULES_MAX) |
| Module source size | 4096 bytes | include/forth/modules.h (FORTH_MODULE_SOURCE_MAX) |
| Module source pool | 32768 bytes | include/forth/modules.h |
| Dependencies per module | 4 | include/forth/modules.h |
LOAD / INCLUDE file size |
4096 bytes | kernel/vios_runtime.c (uses FORTH_MODULE_SOURCE_MAX) |
INCLUDE nesting |
4 | kernel/vios_runtime.c |
| Path length for file services | 1..127 printable characters | kernel/vios_services.c |
FILE-READ / FILE-WRITE transfer |
4096 bytes | kernel/vios_services.c (file_data) |
| Open handles | 8 | kernel/vios_handles.c (HANDLES) |
| Pipes | 4, 128 bytes each | kernel/vios_handles.c |
User devices (/dev/NAME) |
4 | kernel/vios_handles.c (DEVICES) |
| Storage streams | 4 | include/platform/storage.h (STORAGE_STREAMS) |
| Boot source slots | 2 | kernel/vios_boot.c |
| Workbench draft | 4096 bytes | include/vios/workbench.h |
GUI
| Item | Value | Source |
|---|---|---|
| Screen | 640x480, 16 colours (mode 0) | firmware/include/vios_gui.h |
| Windows (display server total / CPU-owned ids) | 33 / 27 (ids 0..26) | firmware/lib/vios-vds/src/vds.h, include/vios/ui.h |
| Surfaces (total / CPU-owned ids) | 17 / 11 (ids 0..10) | firmware/lib/vios-vds/src/vds.h, include/vios/ui.h |
| Sprites | 16 (the topmost is the pointer), up to 64x64 | firmware/lib/vios-vds/src/vds.h |
| Widgets | 64 | firmware/lib/vios-vds/src/vds_ui.h, include/vios/ui.h |
| Menus / commands | 16 / 64 | firmware/lib/vios-vds/src/vds_ui.h |
| Simultaneous animations (tweens) | 16 | firmware/lib/vios-vds/src/vds_ui.h |
| Window title buffer | 32 bytes | firmware/lib/vios-vds/src/vds.h (VDS_TITLE_MAX) |
| Surface rows | 1024 | include/vios/ui.h (VIOS_UI_ROWS) |
| Text widget contents | 4096 bytes | include/vios/ui.h (VIOS_UI_TEXT_MAX) |
| GUI command batch | 250 bytes | kernel/vios_ui.c (BATCH_MAX) |
| CPU event ring | 8 events | kernel/vios_ui.c (EVENT_RING) |
Memory map (eZ80)
| Range | Use | Source |
|---|---|---|
| below 0x040000 | MOS (flash); only the bootstrap, VIOS makes no MOS calls after entry | arch/ez80/start.s |
| 0x040000 | VIOS resident image start (code, data, BSS follow) | boards/agon-light-2/ram.ld |
| up to 0x0AF000 | end of the area the image and BSS may use | boards/agon-light-2/ram.ld |
| 0x0AF000-0x0AFFFF | 4 KiB CPU stack (top at 0x0B0000) | boards/agon-light-2/ram.ld |
| 0x0B0000-0x0BFF00 | MOS's RAM interrupt jump table (48 vectors), which VIOS checks and takes over when the tick starts | kernel/vios_irq.c |
Forth addresses are these native addresses. On the host test build only
three regions exist: token code at 0x010000, direct code at 0x020000 and
data space at 0x040000 (forth/system.c, forth_init).
Clocks and links
| Item | Value | Source |
|---|---|---|
| eZ80 system clock | 18.432 MHz | kernel/vios_irq.c |
| Tick interrupt | 1 kHz (PRT1, reload 288 at /64) | kernel/vios_irq.c |
TIMER@ counter |
288 kHz, 16 bits (wraps every ~227 ms) | kernel/vios_services.c, bench/forth_bench.c |
MILLIS range |
24 bits of the ESP millisecond clock (~4.6 h) | kernel/vios_services.c |
| eZ80 to ESP32 UART (VIOS) | 1152000 baud default; 115200 or 384000 selectable (VIOS_INTERNAL_BAUD) |
Makefile |
| eZ80 to ESP32 UART (MOS phase) | 384000 baud | firmware/include/vios_bridge.h (VIOS_MOS_BAUD) |
| ESP32 USB serial to the Mac | 115200 baud | tools/serial_monitor.py |
| USB frame payload | 240 bytes | include/vios/wire.h (VIOS_WIRE_PAYLOAD_MAX) |
| Host request timeout (VDP queries, host files) | about 1 s | boards/agon-light-2/platform_resident.c |
VIOS and this manual are © 2026 Alessandro Iob, released under the MIT License. More at iob.dev.