Architecture
How the machine is put together at 3.0.0-WP06c: the L0/L1 split, the OCBL boot flow, every L0 subsystem, the 275-program L1 world, and the 20-service SYS_L1SVC surface. Everything below is read straight from the tree.
Two layers by design
L0 is a pure service kernel: kernel + drivers + root services + the numbered interface, and nothing else - no shell, no commands, no TUI, no input method (the 2.x recovery shell was removed in WP-03). L1 is the whole user world in ring 3, and 3.0.0 ships both in one tree under src/L0/ and src/L1/.
OCBL - the in-tree bootloader (hybrid BIOS + UEFI ISO)
16-bit real mode -> 32-bit -> 64-bit long mode, dynamic disk scan
|
+------------------------+------------------------+
| src/L0/boot/ boot.S - kmain - l1_launcher |
| 64-bit entry -> GDT -> identity map -> long mode |
+------------------------+------------------------+
|
src/L0/core/ main -> registry -> sched -> syscall -> crash
(IDT/IST - PMM/VMM/heap - syscalls 54 - klog - DRBG)
|
src/L0/drivers/ src/L0/services/
15 families 24 service folders
acpi block bluetooth time fs block nic snd
camera i2c input misc net ota power health
nic pci scsi sd snd klog watchdog crypto l1
time usb wireless display input camera usb
(OC_DRIVER_DECL) ocembed diag tui ...
SYS_L1SVC(110): 20 services / 190 numbered entries
|
src/L1/ 275 programs - ush (default entry, ring 3)
one command = one app = one folder
|
L0 ready, waiting for L1 -> exit/failure -> L0 halts (reboot or the OCBL menu)
L0 - the pure service kernel
Boot, memory, scheduling, ring-3, VFS, networking, drivers, crash machinery, OTA - laid out as src/L0/boot/ core/ drivers/ services/. 128,890 lines across the tree, zero external runtime dependencies, zero interactive user surface: no shell, no commands, no TUI, no IME live in L0.
L1 - the ring-3 world
275 programs under src/L1/ (242 app folders + 8 flat .c + 25 flat .asm): ush, the TUI desktop, the editor, the Chinese console + pinyin IME, and one command per app - 285 commands = 274 registry apps + 11 ush built-ins, all served through the 20-service SYS_L1SVC surface (190 numbered entries).
Why split at all
A service kernel must stay minimal and trustworthy; user-facing growth happens above it. The kernel self-tests, watchdog, crash policy and log readers stay in L0 as services; if the ring-3 world cannot start, L0 says so honestly and halts - the guidance is a reboot or the OCBL boot menu (there is deliberately no L0 shell to fall back to).
Boot flow
From power-on to the ring-3 ush prompt - both firmware paths, measured on every release. No GRUB anywhere in the 3.0.0 chain.
OCBL - the self-written bootloader
One ISO carries both paths: a 512-byte real-mode stage 1 (El Torito / MBR) for legacy BIOS, and an EFI entry for UEFI. OCBL scans the disks dynamically, shows a boot menu with a 10 s countdown, then loads the OCOS kernel and enters long mode itself - 16-bit → 32-bit → 64-bit.
src/L0/boot/ - the 64-bit entry
boot.S builds the GDT, maps the low identity range, switches paging on and jumps to 64-bit C code; kmain is the first C entry. The BIOS flavor arrives here from OCBL's core head; the UEFI flavor has its own EFI entry that calls the same C bring-up.
kmain - L0 bring-up
One OK line per subsystem: IDT + IST exception stacks, PIT at 100 Hz, PMM over the memory map - then the declared drivers and services are collected from their link sections (OC_DRIVER_DECL / OC_SERVICE_DECL) and initialised, ending at crash recovery armed.
L0 ready, waiting for L1
L0 finishes init and hands the machine to the default L1 entry declared via OC_L1_APP_DECL: ush in ring 3. The launcher prints l1 launcher: booting 'ush' (ring 3, 18968 bytes) and the boot task parks in a scheduler yield loop - there is no interactive kernel shell.
ush> - or an honest halt
The ring-3 world comes up: 274 registry apps plus 11 built-ins. If ush exits or fails to start, L0 does not pretend: it logs l1 launcher: default L1 app exited; L0 halting and parks in the halt loop - the honest guidance is a reboot or the OCBL boot menu. The 2.x oc> recovery fallback was removed in WP-03.
Every release gates on this exact sequence booting clean in QEMU twice - legacy BIOS and UEFI (OVMF).
L0 subsystems - src/L0/
The tree is the architecture - each directory under src/L0/ is one subsystem with a hard contract, and the whole user world lives beside it under src/L1/.
| Subsystem | What it does |
|---|---|
src/L0/boot/ | 64-bit entry (boot.S), kmain bring-up, the L1 launcher and the L1 self-test |
src/L0/core/ | Scheduler, syscalls (54), the app/driver/service registry, crash machinery |
src/L0/core/mem/ | PMM bitmap, 4-level VMM, kmalloc heap |
src/L0/core/lib/ | String, printf, ring buffer, klog |
src/L0/drivers/ | 15 declared driver families, acpi to wireless (OC_DRIVER_DECL) |
src/L0/services/ | 24 service folders - one per L1SVC category plus the kernel-side homes (OC_SERVICE_DECL) |
src/L0/services/fs/ | VFS over FAT32 / exFAT / ext4 / ramfs |
src/L0/services/net/ | TCP/IP, TLS, SSH client + sshd |
src/L0/services/crypto/ | AES / SHA-256 / HMAC / DRBG, RDRAND-seeded |
src/L0/services/ota/ | A/B slots, verified update install |
src/L0/services/sysapi/ | core_syscall.h (54) + l1svc_defs.h - the numbered ABI |
src/L1/ | The ring-3 world: 275 programs - ush, the TUI desktop, the editor, the Chinese console + IME, one command per app |
ocbl/ | OCBL, the in-tree bootloader (BIOS stage1 + EFI entry, the boot menu) |
ocire/ | OCIRE, the independent recovery kernel (separate L0, its own ISO) |
The L1 program world
Everything users actually touch is a ring-3 program under src/L1/ - the shell included. One command = one app = one folder.
The only shell
ush is the default boot entry: 274 registry apps served by name, 11 built-ins (cd, export, alias, jobs, history, ...), pipes, redirection, wildcards, environment - everything a daily shell needs, all in ring 3.
The TUI desktop - an L1 citizen
Desktop, taskbar, menus, form widgets, a full-screen editor and the system apps live under src/L1/ and draw through the L1SVC tui service (services/tui). The 2.x layout with tui/ inside L0 is gone since WP-04.
Chinese console + IME
The CJK layer - 16x16 bitmap font, GB2312/UTF-8 codecs and the interactive pinyin IME - is a ring-3 program family under src/L1/ (chinese/, chinesetest/), riding the display/encoding/font services.
Shared objects
An in-tree ld.so with dlsym and PIE relocations serves the dynamic-linking programs; the solib loader rides the l1 service category.
The L1SVC surface - 20 services / 190 numbered entries
SYS_L1SVC(110): one syscall routes a ring-3 call to the owning L0 service by category; the folder under services/ is the category. Ops are plain ASCII text renderers - the ring-3 side formats nothing. Renumber only by appending (src/L0/services/sysapi/l1svc_defs.h).
| Service | Ops | Folder | Commands |
|---|---|---|---|
| time | 4 | services/time/ | rtc hpet pmtimer tsc |
| block | 23 | services/block/ | ahci nvme ata dskstat lsblk parted mkfs.* fsck sync abdisk install abcfg + tests |
| nic | 20 | services/nic/ | e1000e igb ixgbe rtl-* bcm57xx wifi bt + tests |
| snd | 17 | services/snd/ | sound hda ac97 sb16 es1370 virtiosnd usbaudio play volume + tests |
| power | 8 | services/power/ | shutdown reboot halt sleep + tests |
| ota | 16 | services/ota/ | checkupdate config update rollback + tests |
| fs | 6 | services/fs/ | mount mounts umount fatmount fatstat tree |
| net | 14 | services/net/ | arp dhcp dns dnstest firewall ip lspci nf_test route tcpcc_test tcpstats tcptest |
| display | 12 | services/display/ | stats uname clear lang chinese* font* encoding* ime* |
| camera | 10 | services/camera/ | uvc uvctest scsi scsitest gameport* parallel* ir* |
| usb | 9 | services/usb/ | usb usbdev usb_*_test |
| diag | 9 | services/diag/ | mem frag heap sched syncstat crashlog crashtest dumpinfo + self-test ops |
| tui | 9 | services/tui/ | the full-screen TUI family (desktop, taskbar, menus, forms) |
| health | 3 | services/health/ | health alarms JSON export |
| klog | 3 | services/klog/ | dmesg logctl logcat |
| crypto | 2 | services/crypto/ | cryptotest dhtest |
| input | 2 | services/input/ | touchpad touchtest |
| l1 | 2 | services/l1/ | the solib loader surface |
| ocire | 2 | services/ocembed/ | guard-only: the OCIRE log-agent channel (LOG_APPEND, KLOG_SNAPSHOT) |
| watchdog | 1 | services/watchdog/ | wdt controls |
Caliber: the per-service op counts above sum to 170 command ops; the 190-entry figure (INTERFACES.md) additionally counts the 20 category identifiers - 20 + 170 = 190 numbered entries in l1svc_defs.h.
The command surface - 285 commands
One command = one app = one folder under src/L1/: 274 registry programs plus 11 ush built-ins - and zero commands in L0. The v1→v3 mapping table in INTERFACES.md is the compatibility contract (all 233 v1.0.0 commands mapped, none dropped).
| Home | Commands |
|---|---|
| Ring-3 registry apps (src/L1/, one folder per command) | 274 |
| ush built-ins (cd, export, alias, jobs, history, ...) | 11 |
| L0 kernel shell commands | 0 |
Reliability mechanisms
A service kernel is only credible if it can survive its own failures - these are the mechanisms, all reachable from ring 3 (ush>) through the L1SVC surface.
Crash dumps
Register dump to serial on exception; crashlog persisted to the /etc volume; crashlog replays the last failures after a reboot.
Hardware watchdogs
Intel TCO and ACPI WDAT timers, armed for real - the E2E suite proves a hard reset and a clean second boot. Policy watchdogs kill starving tasks first.
Kernel log
Ring buffer with levels and filters, generation-rotated files (kernel.log, kernel.log.1), dmesg served to ring 3 through the klog service.
Health monitoring
CPU / memory / task / IO sampling with alarms (CPU-LOCKED at 90%+), JSON export through the L1 surface.
Cross-platform build
One tree, three architectures, two host OSes - and it is reproducible.
make all, one command
Kernel, ISO, deterministic source zip and OTA package from a clean tree - tools/build.sh detects or installs the toolchain, build.ps1 covers Windows (WSL2 / MSYS2).
Reproducible by design
SOURCE_DATE_EPOCH-driven archives; the same commit rebuilds the same bytes - the CI pipeline gates every push on it.
ARM64 + RISC-V cross targets
Real bare-metal bring-up shells (PL011 / NS16550A serial, CNTPCT / CLINT timers) that print the banner and heartbeat in QEMU - same tree, different arch.
Fast and configurable
Content-addressed object cache (measured 3.2x on a warm build) and make menuconfig with defconfigs. The 2.x CONFIG_TUI / CONFIG_CHINESE switches are gone since WP-03 - the TUI and the Chinese layer are plain L1 programs now, always built into src/L1/.