====== Lyx OS – Systemarchitektur ======

Diese Seite beschreibt den Aufbau von Lyx OS: die Drei-Domänen-Architektur (TCB / Lyra / User), die Schichten vom UEFI-Boot bis zum Ring-3-Userspace, das Speicherlayout, die Kernel-Module und das Capability-Routing-Gate.

→ [[lyxos:start|Übersicht]] · [[lyxos:syscalls|Syscall-ABI]] · [[lyxos:kernel|Kernel-Interna]]

----

===== 1. Systemschichten =====

<code>
┌──────────────────────────────────────────────────────────┐
│  Ring-3 – User-Domäne (eigene CR3, minimale Capabilities)│
│  Anwendungen, Shell — via SysSpawn aus VFS gestartet     │
│  Nur erlaubte Syscall-Klassen (PLEDGE_*-Bitmask)         │
├──────────────────────────────────────────────────────────┤
│  Ring-3 – Lyra-Domäne (eigene CR3, privilegierter Dienst)│
│  LLM-Inferenz · lyxc-Compiler · Tool-Registry           │
│  Schlägt vor / erteilt Capabilities — erzwingt nie       │
│  Lyra-KI-Agent (WP17) offen; Vega-Compositor (WP17b) ✅  │
├──────────────────────────────────────────────────────────┤
│  Capability Routing Gate (r3_sc_block-Protokoll)         │
│  Nicht-sensible Syscalls: TCB bedient direkt             │
│  Capability-erwerbende Syscalls: → Lyra-Mailbox          │
├──────────────────────────────────────────────────────────┤
│  Ring-0 – TCB (Trusted Computing Base, Lyx-Sprache)      │
│  PMM · VMM · Exceptions/IDT · SMP · Process             │
│  ATA · Disk · MBR · FAT32 · VFS · Keyboard              │
│  Initrd · Locale · Sync · Ring3                          │
│  Deterministisch, WCET-beschränkt — ruft das LLM nie    │
├──────────────────────────────────────────────────────────┤
│  UEFI-Bootloader (NASM, boot.asm)                        │
│  PE32+-Binary — BOOTX64.EFI                              │
├──────────────────────────────────────────────────────────┤
│  UEFI-Firmware (OVMF)  /  PC-Hardware                    │
└──────────────────────────────────────────────────────────┘
</code>

**Mechanismus und Intelligenz sind strikt getrennt:** Der TCB enthält kein LLM und ruft keines auf. Lyra (Ring-3) hält das Modell, der TCB hält die Hardware-Gewalt. Kein ''kernel/ai.lyx''.

----

===== 2. Boot-Ablauf =====

Der Bootloader (''bootloader/boot.asm'', NASM, ~2900 Zeilen) ist ein PE32+-Flat-Binary. UEFI lädt es als ''BOOTX64.EFI'' und ruft ''efi_main(ImageHandle, SystemTable)'' auf (MS x64 ABI).

Schritte:

  - **Begrüßung** über UEFI ''ConOut''
  - **Kernel laden** — ''\\kernel.elf'' vom UEFI SimpleFileSystem lesen
  - **ELF64 parsen** — ''PT_LOAD''-Segmente mappen, BSS nullen
  - **UEFI Memory Map** holen, ''ExitBootServices'' aufrufen
  - **GDT laden** (64-Bit Code 0x08, Data 0x10)
  - **COM1 initialisieren** (0x3F8 — serielle Debug-Ausgabe)
  - **SYSCALL-MSR** (''IA32_LSTAR'') auf den Ring-0-Einsprungpunkt setzen
  - **Page Tables** aufbauen (Identity-Map 4 GB)
  - **Bump-Allocator** ab physisch 0x2000000 (32 MB) initialisieren
  - **Sprung in Kernel-Entry** (''pub fn main(boot_info_ptr: int64)'' in ''kernel.lyx'')

----

===== 3. Speicherlayout =====

^ Adressbereich ^ Inhalt ^
| ''0x0000'' – ''0x0FFF'' | Null-Page (unmapped, für nil-Checks) |
| ''0x1000'' – ''0x1FFFF'' | Bootloader-Code (PE32+ Text-Section) |
| ''0x100000'' – ''0x1FFFFF'' | Bootloader-Heap / Temporäre Strukturen |
| ''0x200000'' – ~ | Kernel-ELF (''PT_LOAD''-Segmente) |
| ''0x2000000'' | Bump-Allocator-Basis (Kernel-Heap) |
| ''0x1800000'' (24 MB) | ''SHELL_PHYS_BASE'' — Ring-3 ELF-Binary (physisch = virtuell mit Identity-Map) |
| ''0x10000000'' (256 MB) | ''USER_HEAP_BASE'' — virtueller Basis für ''user_mmap'' (wächst aufwärts) |
| '' – 4 GB'' | Identity-Map (1:1 physisch ↔ virtuell) |
| ''0xFFFF800000000000''+ | (Zukünftig: höhere Hälfte Kernel-Space) |

**Page-Größen:**
  * Kernel: 2 MB Huge Pages (''PDE'' mit ''PS''-Bit) für die ersten 4 GB
  * Userspace (M5+): 4 KB Seiten für granulare Rechteverwaltung

----

===== 4. Kernel-Module =====

Der Kernel besteht aus 25 Lyx-Units, die beim Build einzeln zu ''.lyu'' vorkompiliert und dann zu ''kernel.elf'' zusammengelinkt werden:

^ Modul ^ Datei ^ Aufgabe ^
| Exceptions | ''exceptions.lyx'' | IDT (256 Gates), CPU-Fault-Routing, ''panic''/''assert'' |
| PMM | ''pmm.lyx'' | Physical Memory Manager — Bitmap-basiert, 4 GB, UEFI-Memory-Map als Basis |
| VMM | ''vmm.lyx'' | Virtual Memory Manager — PML4, Huge Pages, per-Prozess CR3, User-Page-Mapping |
| Process | ''process.lyx'' | Prozess-Modell: ''ProcCreate'', ''ProcActivate'' |
| Sync | ''sync.lyx'' | Synchronisations-Primitive: Spinlock, Mutex, Semaphor — → [[lyxos:sync|Sync-Primitive]] |
| SMP | ''smp.lyx'' | Symmetric Multiprocessing — LAPIC, Trampoline, AP-Startup, Task-API — → [[lyxos:smp|SMP & Tasks]] |
| ATA | ''ata.lyx'' | ATA-Disk-I/O — Legacy (Primary Master) und Multi-Disk (4 Kanäle, vmm_op42-44) |
| Disk | ''disk.lyx'' | Disk-Abstraktion — probt alle 4 ATA-Kanäle beim Start, cacht Sektorzahl + Modell |
| MBR | ''mbr.lyx'' | MBR-Partition-Tabelle — Lesen und Schreiben von Einträgen (Typ 0x0C FAT32 LBA) |
| FAT32 | ''fat32.lyx'' | Vollständige FAT32-Implementierung mit LFN-Lesen und LFN-Schreiben |
| VFS | ''vfs.lyx'' | Virtual-Filesystem-Layer — FAT32 + Initrd; open/read/write/stat/seek/mkdir/dir/dup |
| Keyboard | ''keyboard.lyx'' | Tastatureingabe (PS/2), Tastaturbelegung (Layout-Index via ''KbdSetLayout'') |
| Initrd | ''initrd.lyx'' | In-Memory-Ramdisk (Format: ''LIXR''-Magic + Einträge + 4B-Terminator) |
| Locale | ''locale.lyx'' | Internationalisierung — 5 Locales, Zahlen-/Zeit-/Datumsformat, ''LocaleInit'' liest ''/config/locale.cfg'' |
| Ring-3 | ''ring3.lyx'' | ELF64-Loader, ''SysSpawn'', Syscall-Handler, Capability Routing Gate (PLEDGE_*) — → [[lyxos:prozesse|Prozesse & Ring-3]] |
| XHCI | ''xhci.lyx'' | USB 3.x-Host-Controller-Treiber — Enumerierung, Datentransfer (WP25) → [[lyxos:xhci|XHCI]] |
| RAM-Disk | ''ramdisk.lyx'' | RAM-Disk-Treiber, Disk-IDs 4–7 — Syscalls 153–154 (WP30) → [[lyxos:ramdisk|RAM-Disk]] |
| IOFS-Alloc | ''iofs_alloc.lyx'' | Block-Allocator, mkfs, CRC32C, Page-I/O — Syscall 155 (WP01+WP09) |
| IOFS-RW | ''iofs_rw.lyx'' | Mount, Read/Write, Checkpoint — Syscalls 156–164 (WP02) |
| IOFS-WAL | ''iofs_wal.lyx'' | Write-Ahead-Log — kernel-intern, kein Syscall (WP04) |
| IOFS-Graph | ''iofs_graph.lyx'' | Graph-Kanten — Syscalls 165–169 (WP05) |
| IOFS-Traverse | ''iofs_traverse.lyx'' | Graph-Traversal BFS/DFS/Reachable/ShortestPath — Syscalls 170–173 (WP06) |
| IOFS-Names | ''iofs_names.lyx'' | Named Nodes, Name-Store, GC — Syscalls 174–179 (WP07+GC) → [[lyxos:iofs|IOFS]] |
| Net + TCP | ''net.lyx'' | E1000-Treiber, DHCP, ARP, TCP — Syscalls 180–184 (WP26, WP16-TCP) → [[lyxos:syscalls|Syscall-ABI]] |
| Kernel | ''kernel.lyx'' | Einstiegspunkt — importiert und initialisiert alle Module |

**Initialisierungsreihenfolge** in ''kernel.lyx'':

<code>
PMM → VMM → RNG-Seed → SMP → VFS (→ Fat32VolumeInit, MbrInit) → DiskInit
  → FAT32-Mount → LocaleInit → Initrd-Mount → SysSpawn (Ring-3 Shell)
  → Keyboard-Poll → Sync-Tests → Scheduler (ProcInit, ProcActivate)
</code>

----

===== 5. Syscall-Grenze =====

Ring-3-Code kommuniziert mit dem Kernel über einen gemeinsamen Speicherblock (''r3_sc_block'') und einen dedizierten Trigger-Mechanismus — kein traditionelles ''SYSCALL''-Register-Layout.

**r3_sc_block-Protokoll:**

<code>
// Shared block (physische Adresse wird bei Boot-Start übergeben)
offset  0: nr      — Syscall-Nummer (int64)
offset  8: a0      — Argument 0 (int64)
offset 16: a1      — Argument 1 (int64)
offset 24: a2      — Argument 2 (int64)
offset 32: a3      — Argument 3 (int64)
offset 40: result  — Rückgabewert (int64), wird vom Kernel geschrieben

// Ablauf aus Ring-3-Sicht:
var sc: int64 := lyx_get_r3sc();    // einmalig: mmap(0,-5,...) → Blockadresse holen
poke64(sc + 0, NR);                 // Syscall-Nummer schreiben
poke64(sc + 8, arg0);               // Argumente schreiben
lyx_trigger();                      // mmap(0,-6,...) → Kernel-Handler aufrufen
var result: int64 := peek64(sc + 40);
</code>

  * ''lyx_get_r3sc()'' und ''lyx_trigger()'' sind keine echten mmap-Aufrufe — der Bootloader fängt negative Größen als ''vmm_op''-Sentinel ab (op -5 = Block-Adresse holen, op -6 = Trigger).
  * User-virtuelle Puffer-Adressen (z.B. Lese-Buffer) werden im Kernel via ''VmmPhysFromUserVirt(proc_cr3, vaddr)'' in physische Adressen übersetzt, bevor sie an VFS-Funktionen weitergegeben werden.
  * Ring-3-FDs sind VFS-FDs + 3 (fd 0 bleibt für stdin/Keyboard reserviert).

→ Implementierung im Kernel: ''ring3.lyx'' (''handle_r3_syscall'') · Vollständige ABI-Spezifikation: [[lyxos:syscalls|Syscall-Referenz]] · Prozess-Lebenszyklus: [[lyxos:prozesse|Prozesse & Ring-3]]

----

===== 6. Capabilities — alles ist ein fd =====

Lyx OS kennt keine root-Privileg-Eskalation. Jeder ''fd'' ist eine **Capability**: er kodiert sowohl die Ressource als auch die erlaubten Operationen (Lesen, Schreiben, Mappen, Löschen …). Capabilities können nur eingeschränkt, nie erweitert werden.

^ Designprinzip ^ Konsequenz ^
| Kein Root | Kein ''chmod 4755'', kein ''sudo''-Äquivalent |
| CLOEXEC by default | Neue ''fd'' werden nicht über ''sys_spawn'' vererbt — opt-in mit ''O_INHERIT'' |
| Ein ''fd''-Typ | ''fd'' für Dateien, Sockets, Prozesse, AI-Sessions sind konzeptuell gleich |
| Alle Pfad-Syscalls nehmen ''dir_fd'' | ''AT_CWD'' als Default — keine TOCTOU-Lücken durch absolute Pfade |

**PLEDGE_*-Bitmask (implementiert in ''ring3.lyx''):**

<code lyx>
pub con PLEDGE_STDIO:  int64 := 1;   // stdin/stdout lesen/schreiben
pub con PLEDGE_VFS:    int64 := 2;   // sys_open, sys_read, sys_write, stat
pub con PLEDGE_EXEC:   int64 := 4;   // sys_spawn
pub con PLEDGE_BLOCK:  int64 := 8;   // Raw-Block-Device-Zugriff
pub con PLEDGE_NET:    int64 := 16;  // Netzwerk-Sockets
pub con PLEDGE_PROC:   int64 := 32;  // Prozess-Management (kill, nice …)
pub con PLEDGE_ALL:    int64 := 63;  // alle Capabilities

SysPledge(PLEDGE_STDIO | PLEDGE_VFS);  // Capabilities einschränken (irreversibel)
</code>

Der **Capability Routing Gate** in ''handle_r3_syscall'' prüft für jede Syscall-Nummer die benötigte Capability-Klasse (''syscall_capability_class'') gegen die ''pledge_mask'' des Prozesses. Verstöße erzeugen ''ERR_CAPVIOL'' (Implementierung: WP15).

→ Details: [[lyxos:prozesse|Prozesse & Ring-3]]

===== 7. Drei-Domänen-Architektur =====

Lyx OS teilt den Adressraum perspektivisch in drei Domänen auf:

^ Domäne ^ Ring ^ Beschreibung ^
| **TCB** (Trusted Computing Base) | Ring-0 | Kernel: deterministisch, vollständiger Hardware-Zugriff |
| **Lyra** | Ring-3 privilegiert | KI-Agent + privilegierter Service (geplant: WP17); bekommt ''PLEDGE_ALL'' |
| **User** | Ring-3 minimal | Anwendungen (z.B. Shell) mit eingeschränkten Capabilities via ''SysPledge'' |

Heute läuft ausschließlich die Shell als Ring-3-Prozess. Lyra (WP17) ist noch nicht implementiert.

Letzte Aktualisierung: 2026-06-25