Architecture
How the machine is put together: the L0/L1 split, the boot flow, every kernel subsystem, the TUI desktop, and the 17-service SYS_L1SVC surface. Everything below is read straight from the tree.
Two layers by design
L0 is the kernel plus the recovery shell; L1 is the ring-3 service world - and 2.2.0 ships both in one tree: the kernel boots straight into its default ring-3 application, with the oc> recovery shell as the always-there fallback.
GRUB 2.12 (hybrid BIOS + UEFI ISO)
| multiboot2 + kernel-as-module
+------------------------+------------------------+
| boot/boot.S |
| 32-bit entry -> GDT -> 2 MiB identity map -> long mode |
+------------------------+------------------------+
|
core/ main -> registry -> sched -> syscall -> crash
(IDT/IST - PMM/VMM/heap - syscalls 54 - klog - DRBG)
|
drivers/ services/ recovery/
26 declared 17 declared oc> shell
block usb nic time fs block nic 99 commands
snd acpi i2c snd ota power net self-tests
time bt sd cam display input camera crash policy
(OC_DRIVER_DECL) usb crypto klog... log readers
|
SYS_L1SVC(110): 17 services / 158 numbered ops
|
l1apps/ ush (default boot entry, ring 3)
ld.so + dynlink tests (shared objects)
|
exit / failure -> oc> recovery shell
L0 - the kernel and the recovery shell
Boot, memory, scheduling, ring-3, VFS, networking, drivers, TUI, crash recovery, OTA - restructured into core/ drivers/ services/ boot/ recovery/. 130,505 lines across 378 source files, zero external runtime dependencies.
L1 - the ring-3 service world
2.2.0 ships it in-tree: 17 SYS_L1SVC services with 158 numbered ops behind one syscall, plus the ush shell, ld.so and the dynamic-linking programs under l1apps/. The v1→v2 command mapping is the compatibility contract.
Why split at all
A recovery-first 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; the oc> shell always works, even when the ring-3 world cannot start.
Boot flow
From power-on to the shell prompt - both firmware paths, measured on every release.
GRUB 2.12 - hybrid BIOS + UEFI
One ISO image carries both boot paths. GRUB hands over the machine via multiboot2 and attaches the kernel ELF as its own install payload.
boot/boot.S - the 32-bit trampoline
Entry at 0x100000, builds the GDT, maps the first 2 MiB identity, switches paging on and jumps to 64-bit long mode - 16 assembly screens of exactly that.
core/main.c - bring-up
One OK line per subsystem: multiboot2 handshake, framebuffer, 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 and initialised.
ush> - the ring-3 shell
The launcher boots the default L1 entry: ush in ring 3, with 133 service commands plus built-ins over pipes, jobs and scripting; A/B slot menu when an update is staged. exit (or a launch failure) falls through to the recovery shell.
oc> - the recovery fallback
99 commands for the recovery environment: kernel self-tests, watchdog and crash-policy controls, log readers, chipset diagnostics, file tools - always available, even when the ring-3 world cannot start.
Every release gates on this exact sequence booting clean in QEMU twice - legacy BIOS and UEFI (OVMF).
Kernel subsystems
The tree is the architecture - each directory is one subsystem with a hard contract.
| Subsystem | What it does |
|---|---|
arch/ | x86_64 entry and CPU plumbing |
core/ | Scheduler, syscalls (54), registry, crash machinery |
core/mem/ | PMM bitmap, 4-level VMM, kmalloc heap |
services/crypto/ | AES / SHA-256 / HMAC / DRBG, RDRAND-seeded |
core/lib/ | String, printf, ring buffer, klog |
services/ota/ | A/B slots, verified update install |
services/ | 17 declared services, one folder per L1SVC category |
drivers/ | 26 declared drivers, block to wireless |
services/fs/ | VFS over FAT32 / exFAT / ext4 / ramfs |
services/net/ | TCP/IP, TLS, SSH client + sshd |
l1apps/ | Ring-3 applications: ush, ld.so, dynlink tests |
recovery/ | The oc> recovery shell, 99 commands |
tui/ | Desktop, taskbar, forms, editor |
chinese/ | CJK console, 16x16 font, pinyin IME |
l1/ | The extension surface + solib loader |
The TUI desktop
A real desktop environment on the raw framebuffer - no GPU stack, no compositor, just the kernel renderer.
Desktop + taskbar
Window list, running apps, clock, system tray area - driven from the framebuffer console the kernel itself renders.
Apps, menus, forms
Menu system, form widgets, a full-screen editor and the system apps (system info, network, hardware) - 9 TUI commands in the shell.
Chinese console + IME
A dedicated CJK layer: 16x16 bitmap font, GB2312/UTF-8 codecs and an interactive pinyin IME (ime -i) on both the console and the TUI.
One renderer, three outputs
The same cell grid renders to the VGA text buffer, the linear framebuffer and the TUI - font engines are swappable through the L1 surface.
The L1SVC surface - 17 services / 158 ops
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 (services/l1/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 (L0 keeps survival controls) |
| ota | 16 | services/ota/ | checkupdate config update rollback + tests |
| fs | 6 | services/fs/ | mount mounts umount fatmount fatstat tree |
| net | 12 | 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* |
| input | 2 | services/input/ | touchpad touchtest |
| camera | 10 | services/camera/ | uvc uvctest scsi scsitest gameport* parallel* ir* |
| usb | 9 | services/usb/ | usb usbdev usb_*_test |
| crypto | 2 | services/crypto/ | cryptotest dhtest |
| health / klog / watchdog / l1: kernel-side services with no ring-3 ops yet (log readers and watchdog stay L0 by design) | |||
The command surface - 251 commands
Every 1.0.0 command is mapped: 134 moved to the ring-3 surface (133 SVC rows + the NETCMD bridge), 99 stay in the L0 recovery shell, 19 run as ush built-ins. The v1→v2 mapping table in INTERFACES.md is the compatibility contract.
| Home | Commands |
|---|---|
| Ring-3 service commands (SYS_L1SVC) | 133 |
| ush built-ins (files, jobs, net bridge) | 19 |
| L0 recovery shell - kernel self-tests, watchdog, crash policy, log readers | 29 |
| L0 recovery shell - chipset diagnostics (ACPI/PCI/i2c) | 16 |
| L0 recovery shell - files and the editor | 16 |
| L0 recovery shell - task/memory diagnostics | 9 |
| L0 recovery shell - interactive sessions (ssh/sshd), power survival controls | 6 |
| L0 recovery shell - time sources + misc | 23 |