This folder describes how Tyrne is designed. The why behind each design choice lives in ../decisions/; the documents here focus on the how — the structure, the interactions, and the data flow.
The architecture is being written in phases. Many documents listed below are planned but not yet written. They will be added as the ADRs for the corresponding subsystems are accepted.
| Document | Purpose | Status |
|---|---|---|
overview.md |
Top-level structure: kernel, userspace, HAL, boot flow; with Mermaid diagrams. | Accepted |
security-model.md |
Capability system, trust boundaries, threat model. | Accepted |
hal.md |
Hardware Abstraction Layer: trait surfaces, board support packages, portability. | Accepted |
boot.md |
Boot flow from reset vector through kernel init to first userspace task. | Accepted (v0.0.1 — QEMU virt; T-013 EL drop landed) |
scheduler.md |
Cooperative FIFO scheduler: ready queue, idle task, raw-pointer IPC bridge, ContextSwitch trait. | Accepted (v0.0.1 — single-core, no preemption) |
ipc.md |
Inter-process communication: synchronous send/recv, endpoint state machine, capability transfer, scheduler-bridge wrappers. | Accepted (v0.0.1 — depth-1 endpoints; IpcError taxonomy split per ADR-0030) |
exceptions.md |
Exception vector table, IRQ dispatch, GIC v2 driver, generic-timer IRQ wiring, idle WFI activation. | Accepted (v0.0.1 — T-012 Done 2026-04-28 via PR #10 merge; design + implementation match; maintainer-side QEMU smoke verification of the deliberate-deadline path remains pre-B1-closure work) |
memory-management.md |
Physical + virtual memory, MMU/paging, allocators, address-space objects, task loader. | Accepted (v0.0.1 — MMU/PMM/AddressSpace/loader; T-016..T-019) |
task-loader.md |
Task loader: raw-flat image → populated address space; rollback contract; audit-log surface. | Accepted (v0.0.1 — T-019) |
drivers.md |
Userspace driver model, capability grants, driver API. | Planned |
userspace.md |
Init process, system services, shell, root of trust. | Planned |
Start with overview.md, then follow the subsystem that interests you. The security model cross-cuts everything and is worth reading early.
- Architectural diagrams use Mermaid (see ../standards/documentation-style.md).
- Every subsystem document begins with a one-paragraph summary suitable for someone skimming the tree.
- Code snippets in architecture documents are illustrative pseudocode unless explicitly marked as real source.
- Every architectural claim of the form "Tyrne does X because Y" should link to the ADR that made that choice.