UmkaOS Architecture Design Document

Canonical reference for all development. This document defines the complete architecture of UmkaOS. All implementation decisions must trace back to this specification.

The architecture is organized into 24 chapters using chapter-scoped section numbering. Cross-references are clickable links between files.

Copyright © 2026 Anton Starikov \<ant.starikov@gmail.com> All rights reserved. This design document is the original work of the author. Reproduction or distribution without explicit permission is prohibited.

How to Read This Document

Section numbering uses Chapter.Section format:

Section 10.4 = Chapter 10, Section 4 (in 10-drivers.md)
Section 10.4.2 = Chapter 10, Section 4, Subsection 2
Adding sections to one chapter never affects other chapters

Cross-references are clickable markdown links: [Section 13.2 Mount Tree](13-vfs.md#132-mount-tree-data-structures-and-operations)

Master Index

Chapter	File	Domain
1	01-overview.md	Design philosophy, architectural goals, performance budget
2	02-boot-hardware.md	Boot chain, device discovery, ACPI/DT, multi-architecture support, hardware memory safety
3	03-concurrency.md	Locking strategy, lock-free structures, PerCpu, RCU, atomic operations, memory ordering, interrupt handling, error handling
4	04-memory.md	Physical allocator, virtual memory, page tables, slab, NUMA, compression tier, page cache, extended memory operations
5	05-distributed.md	Cluster topology, distance matrix, RDMA transport, distributed shared memory, distributed lock manager, SmartNIC/DPU integration
6	06-scheduling.md	EEVDF, RT, deadline scheduling, per-CPU runqueues, EAS, power budgeting, CPU bandwidth, timekeeping, intent-based resource management
7	07-process.md	Task/Process structs, fork/exec/exit, real-time guarantees, signal handling, process groups/sessions, resource limits and accounting
8	08-security.md	Capabilities, credentials, LSM framework, verified boot, TPM, IMA, post-quantum cryptography, confidential computing
9	09-security-extensions.md	Kernel crypto API, kernel key retention service, seccomp-BPF syscall filter, ARM MTE, DebugCap
10	10-drivers.md	Three-tier protection model, isolation mechanisms, driver isolation tiers, device registry, zero-copy I/O, IPC, crash recovery, USB, I2C
11	11-kabi.md	Stable driver ABI (KABI), KABI IDL, vtable design, driver signing, compatibility windows
12	12-device-classes.md	NIC, GPU, WiFi, Bluetooth, camera, printers, live kernel evolution, watchdog, SPI, rfkill, MTD, IPMI, UIO, NVMEM, SoundWire
13	13-vfs.md	VFS architecture, dentry cache, mount tree, path resolution, overlayfs, binfmt_misc, autofs, file notifications, file locking, disk quotas, pipes/FIFOs
14	14-storage.md	Durability guarantees, block I/O, volume management, block storage networking, clustered filesystems, DLM, persistent memory, computational storage, SATA/AHCI, ext4/XFS/Btrfs, ZFS, NFS client/server, I/O priority
15	15-networking.md	Socket layer, NetBuf, routing, TCP stack, congestion control, kTLS, overlays/tunnels, netlink, packet filtering, interface naming, tc/qdisc, IPsec/XFRM, SCTP, AF_VSOCK, VLAN, IPVS
16	16-containers.md	Namespace architecture (8 types), cgroups v2, POSIX IPC
17	17-virtualization.md	KVM host/guest integration, VMX/VHE/H-ext, live migration, PV features, suspend/resume, VFIO/iommufd device passthrough
18	18-compat.md	Syscall interface, futex, netlink, Windows emulation, dropped compatibility, native syscalls, safe extensibility, special FD objects, typed event notification
19	19-observability.md	Fault management architecture, stable tracepoints, debugging/ptrace, unified object namespace (umkafs), EDAC, pstore, PMU/perf_event_open, typed sysctl
20	20-user-io.md	TTY/PTY, input (evdev), audio (ALSA), display/graphics (DRM/KMS)
21	21-accelerators.md	Unified accelerator framework, accelerator memory/P2P DMA, isolation/scheduling, in-kernel inference, accelerator networking, unified compute model
22	22-ml-policy.md	AI/ML policy framework: closed-loop kernel intelligence, KernelObservation bus, KernelTunableParam store, PolicyConsumerVTable
23	23-roadmap.md	Driver ecosystem, implementation phases, verification strategy, technical risks, formal verification, appendices
24	24-agentic.md	Development model, parallel workflow, phase timelines, sensitivity analysis, recommendations
—	00-review-primer.md	Review guidance

Parts

Part I: Foundations

Chapter 1: Architecture Overview — Design philosophy, architectural goals, performance budget
Chapter 2: Boot and Hardware Discovery — Boot chain, device discovery, ACPI/DT, multi-architecture support, hardware memory safety
Chapter 3: Concurrency Model — Locking strategy, lock-free structures, PerCpu, RCU, atomic operations, memory ordering, interrupt handling
Chapter 4: Memory Management — Physical allocator, virtual memory, page tables, slab, NUMA, compression tier, page cache, extended memory operations
Chapter 5: Distributed Kernel Architecture — Cluster topology, distance matrix, RDMA transport, distributed shared memory, distributed lock manager, SmartNIC/DPU integration

Part II: Core Subsystems

Chapter 6: Scheduling and Power Management — EEVDF, RT, deadline scheduling, per-CPU runqueues, EAS, power budgeting, CPU bandwidth, timekeeping
Chapter 7: Process and Task Management — Task/Process structs, fork/exec/exit, real-time guarantees, signal handling, process groups/sessions, resource limits
Chapter 8: Security Architecture — Capabilities, credentials, LSM framework, verified boot, TPM, IMA, post-quantum cryptography, confidential computing
Chapter 9: Security Extensions — Kernel crypto API, kernel key retention service, seccomp-BPF syscall filter, ARM MTE, DebugCap
Chapter 10: Driver Architecture and Isolation — Three-tier protection model, isolation mechanisms, driver isolation tiers, device registry, zero-copy I/O, IPC, crash recovery, USB, I2C
Chapter 11: KABI — Kernel Driver ABI — Stable driver ABI, KABI IDL, vtable design, driver signing, compatibility windows
Chapter 12: Device Class Frameworks — NIC, GPU, WiFi, Bluetooth, camera, printers, live kernel evolution, watchdog, SPI, rfkill, MTD, IPMI, UIO, NVMEM, SoundWire

Part III: Major Subsystems

Chapter 13: Virtual Filesystem Layer — VFS architecture, dentry cache, mount tree, path resolution, overlayfs, binfmt_misc, autofs, file notifications, file locking, disk quotas, pipes/FIFOs
Chapter 14: Storage and Filesystems — Durability guarantees, block I/O, volume management, block storage networking, clustered filesystems, DLM, persistent memory, SATA/AHCI, ext4/XFS/Btrfs, ZFS, NFS, I/O priority
Chapter 15: Networking — Socket layer, NetBuf, routing, TCP stack, congestion control, kTLS, overlays/tunnels, netlink, packet filtering, interface naming, tc/qdisc, IPsec, SCTP, VSOCK, VLAN, IPVS
Chapter 16: Containers and Namespaces — Namespace architecture (8 types), cgroups v2, POSIX IPC
Chapter 17: Virtualization — KVM host/guest integration, VMX/VHE/H-ext, live migration, PV features, suspend/resume, VFIO/iommufd device passthrough
Chapter 18: Linux Compatibility — Syscall interface, futex, netlink, Windows emulation, dropped compatibility, native syscalls, safe extensibility, special FD objects, typed event notification

Part IV: Specialized Subsystems

Chapter 19: Observability and Diagnostics — Fault management architecture, stable tracepoints, debugging/ptrace, unified object namespace (umkafs), EDAC, pstore, PMU/perf, typed sysctl
Chapter 20: User I/O Subsystems — TTY/PTY, input (evdev), audio (ALSA), display/graphics (DRM/KMS)
Chapter 21: AI/ML and Accelerators — Unified accelerator framework, accelerator memory/P2P DMA, isolation/scheduling, in-kernel inference, accelerator networking, unified compute model
Chapter 22: AI/ML Policy Framework — Closed-loop kernel intelligence, KernelObservation bus, KernelTunableParam store, PolicyConsumerVTable, reference ML services

Part V: Meta

Chapter 23: Roadmap and Verification — Driver ecosystem, implementation phases, verification strategy, technical risks, formal verification, appendices
Chapter 24: Agentic Development Methodology — Development model, parallel workflow, phase timelines, sensitivity analysis, recommendations