====== Lyx OS – Syscall-ABI v1.0 ====== Diese Seite dokumentiert die vollständige Syscall-Schnittstelle von Lyx OS. Sie richtet sich an Entwickler, die Ring-3-Anwendungen schreiben, Kernel-nahe Bibliotheken implementieren oder Syscalls direkt in NASM-Assembly nutzen. → [[lyxos:anwendungen|Anwendungen entwickeln]] · [[lyxos:architektur|Architektur]] · [[lyxos:start|Übersicht]] ---- ===== 1. Aufrufkonvention ===== Lyx OS nutzt ausschließlich die ''SYSCALL''/''SYSRET''-Instruktion (AMD64 Fast Syscall). Es gibt keine Int-80-Kompatibilität und kein Vsyscall-Interface. ==== Register-Layout ====


Eingabe:
  rax  = Syscall-Nummer (0x0000 – 0x0CFF)
  rdi  = Argument 1
  rsi  = Argument 2
  rdx  = Argument 3
  r10  = Argument 4  (statt rcx — wird vom SYSCALL-Mechanismus überschrieben)
  r8   = Argument 5
  r9   = Argument 6

Ausgabe:
  rax  = Fehlercode  (0 = Erfolg; >0 = ERR_* Konstante)
  rdx  = Rückgabewert (fd, Adresse, Byte-Anzahl, PID, ...)

Nicht verändert (callee-saved):  rbx, rbp, r12–r15
CLOBBERT:                        rcx, r11 (SYSCALL-Mechanismus)
                                 rdi, rsi, r10, r8, r9

==== Zwei-Register-Rückgabe ==== Das Design-Alleinstellungsmerkmal: Fehler und Nutzwert kommen in **zwei getrennten Registern**. Kein globales ''errno'', kein Vorzeichentest auf einem einzigen Register.


rax = 0      → Erfolg; Nutzwert steht in rdx
rax = ERR_*  → Fehler; rdx ist undefiniert

''lyxc --target=lyxos'' übersetze das als Tupel-Syntax:


var fd, err := sys_open(AT_CWD, "config.txt", O_READ, 0);
if (err != ERR_OK) {
    EPrintLn("open fehlgeschlagen: " + IntToStr(err));
    return 1;
}

==== NASM-Beispiel ====


; sys_write(FD_STDOUT, buf, len)  →  bytes_written in rdx, Fehler in rax
mov  rax, 0x0203        ; sys_write
mov  rdi, 1             ; arg1: fd = FD_STDOUT
mov  rsi, buf           ; arg2: Puffer
mov  rdx, len           ; arg3: Länge
syscall
test rax, rax
jnz  .error             ; rax ≠ 0 → Fehler
; rdx = Anzahl tatsächlich geschriebener Bytes

==== lyxc-Builtin-Mapping ==== ^ lyxc-Builtin ^ LyxOS-Syscall ^ | ''PrintLn(s)'' | ''sys_write(FD_STDOUT, ...)'' | | ''EPrintLn(s)'' | ''sys_write(FD_STDERR, ...)'' | | ''mmap(...)'' | ''sys_mmap(...)'' | | ''open(path, ...)'' | ''sys_open(AT_CWD, path, ...)'' | | ''read(fd, ...)'' | ''sys_read(fd, ...)'' | | ''write(fd, ...)'' | ''sys_write(fd, ...)'' | | ''close(fd)'' | ''sys_close(fd)'' | ---- ===== 2. Fehlercodes =====


con ERR_OK          : int64 := 0   // Erfolg
con ERR_PERM        : int64 := 1   // Zugriff verweigert
con ERR_NOENT       : int64 := 2   // Datei / Ressource nicht gefunden
con ERR_BUSY        : int64 := 3   // Ressource belegt
con ERR_IO          : int64 := 4   // I/O-Fehler
con ERR_NOMEM       : int64 := 5   // Kein Speicher
con ERR_AGAIN       : int64 := 6   // Nochmal versuchen (würde blockieren)
con ERR_INVAL       : int64 := 7   // Ungültiges Argument
con ERR_OVERFLOW    : int64 := 8   // Puffer- / Wert-Überlauf
con ERR_TIMEOUT     : int64 := 9   // Zeitüberschreitung
con ERR_EXIST       : int64 := 10  // Existiert bereits
con ERR_NOTDIR      : int64 := 11  // Kein Verzeichnis
con ERR_ISDIR       : int64 := 12  // Ist ein Verzeichnis
con ERR_NOTEMPTY    : int64 := 13  // Verzeichnis nicht leer
con ERR_BADFD       : int64 := 14  // Ungültiger File-Deskriptor
con ERR_NOSYS       : int64 := 15  // Syscall nicht implementiert
con ERR_NOTSUP      : int64 := 16  // Operation nicht unterstützt
con ERR_RANGE       : int64 := 17  // Wert außerhalb des gültigen Bereichs
con ERR_FAULT       : int64 := 18  // Ungültige Speicheradresse
con ERR_LOOP        : int64 := 19  // Symbolischer-Link-Schleife
con ERR_NAMETOOLONG : int64 := 20  // Pfad-Komponente zu lang
con ERR_NOTCONN     : int64 := 21  // Socket nicht verbunden
con ERR_CONNREFUSED : int64 := 22  // Verbindung abgelehnt
con ERR_ADDRUSE     : int64 := 23  // Adresse bereits in Benutzung
con ERR_BROKEN      : int64 := 24  // Verbindung / Pipe getrennt
con ERR_CANCELED    : int64 := 25  // Operation abgebrochen
con ERR_DEADLOCK    : int64 := 26  // Würde Deadlock verursachen
con ERR_TOOBIG      : int64 := 27  // Argument / Daten zu groß
con ERR_NODEV       : int64 := 28  // Kein solches Gerät
con ERR_CAPVIOL     : int64 := 29  // Capability-Verletzung
con ERR_AIBUSY      : int64 := 30  // KI-Inferenz-Engine ausgelastet
con ERR_BADMODEL    : int64 := 31  // Ungültiges oder nicht unterstütztes KI-Modell
con ERR_CTXFULL     : int64 := 32  // KI-Kontextfenster voll

---- ===== 3. Standard-Konstanten =====


// Standard-File-Deskriptoren
con FD_STDIN  : int64 := 0
con FD_STDOUT : int64 := 1
con FD_STDERR : int64 := 2

// Spezielle dir_fd-Werte (alle Pfad-Syscalls nehmen dir_fd als erstes Argument)
con AT_CWD  : int64 := -1   // Aktuelles Arbeitsverzeichnis
con AT_ROOT : int64 := -2   // Dateisystem-Wurzel


con PROT_NONE  : int64 := 0
con PROT_READ  : int64 := 1
con PROT_WRITE : int64 := 2
con PROT_EXEC  : int64 := 4

con MAP_PRIVATE   : int64 := 1
con MAP_SHARED    : int64 := 2
con MAP_ANONYMOUS : int64 := 4
con MAP_FIXED     : int64 := 8
con MAP_POPULATE  : int64 := 16   // Seiten sofort einpagen


con O_READ      : int64 := 1
con O_WRITE     : int64 := 2
con O_RDWR      : int64 := 3
con O_CREAT     : int64 := 4
con O_EXCL      : int64 := 8
con O_TRUNC     : int64 := 16
con O_APPEND    : int64 := 32
con O_NONBLOCK  : int64 := 64
con O_INHERIT   : int64 := 128   // fd über sys_spawn vererben (CLOEXEC ist Default)
con O_DIRECTORY : int64 := 256
con O_TMPFILE   : int64 := 512


con CLOCK_REAL   : int64 := 0   // Wanduhr (UTC, kann springen)
con CLOCK_MONO   : int64 := 1   // Monoton seit Boot
con CLOCK_CPU    : int64 := 2   // CPU-Zeit des aktuellen Prozesses
con CLOCK_THREAD : int64 := 3   // CPU-Zeit des aktuellen Threads


// Capability-Rechte
con RIGHT_READ    : int64 := 1
con RIGHT_WRITE   : int64 := 2
con RIGHT_EXEC    : int64 := 4
con RIGHT_MMAP    : int64 := 8
con RIGHT_SEEK    : int64 := 16
con RIGHT_STAT    : int64 := 32
con RIGHT_DELETE  : int64 := 64
con RIGHT_CONTROL : int64 := 128
con RIGHT_ALL     : int64 := 0x7FFFFFFFFFFFFFFF


con TASK_DETACHED          : int64 := 1
con TASK_CPU_INTENSIVE     : int64 := 2
con TASK_IO_INTENSIVE      : int64 := 4
con TASK_LATENCY_SENSITIVE : int64 := 8
con TASK_INHERIT_CAPS      : int64 := 16

==== Kategorie 0x0A00 – Debug & Telemetrie ==== ^ Nr ^ Name ^ Argumente ^ Rückgabe (rdx) ^ Beschreibung ^ | 0x0A00 | ''sys_debug_print'' | ''msg, len'' | — | Kernel-Debug-Ausgabe (Port 0xE9 / COM1); No-Op in Release | | 0x0A01 | ''sys_trace_event'' | ''event_id, data*, len'' | — | Trace-Event in Kernel-Ringpuffer | | 0x0A02 | ''sys_perf_counter'' | ''counter_id'' | Wert | Hardware-Performance-Counter (RDPMC) | | 0x0A03 | ''sys_stack_trace'' | ''buf*, size'' | Frame-Anzahl | Aktuelle Rücksprungadressen in Puffer schreiben | | 0x0A04 | ''sys_watchpoint_set'' | ''addr*, size, flags'' | Watchpoint-ID | Hardware-Watchpoint setzen (DR0–DR3) | | 0x0A05 | ''sys_watchpoint_clear'' | ''wp_id'' | — | Hardware-Watchpoint löschen | ==== Kategorie 0x0C00 – IOFS ==== Niedrig-Level-Zugang zum Island & Ocean File System. Normale Anwendungen nutzen das VFS-Interface. ^ Nr ^ Name ^ Argumente ^ Rückgabe (rdx) ^ Beschreibung ^ | 0x0C00 | ''sys_iofs_mount'' | ''dev_fd, IofsOpts*'' | mount_fd | Raw-Block-Device als IOFS einbinden | | 0x0C01 | ''sys_iofs_compact'' | ''mount_fd, region_hint'' | Pages | Manuellen Kompaktierungszyklus auslösen | | 0x0C02 | ''sys_iofs_page_info'' | ''mount_fd, page_id, IofsPageInfo*'' | — | IOFS-Page-Header und Metadaten lesen | | 0x0C03 | ''sys_iofs_sandbox_enter'' | ''mount_fd'' | — | Panic-Sandbox aktivieren (CAP_ADMIN erforderlich) | | 0x0C04 | ''sys_iofs_sandbox_exit'' | — | — | Panic-Sandbox verlassen | ---- ===== 5. Übersicht aller Kategorien ===== ^ Bereich ^ Kategorie ^ Syscall-Anzahl ^ | 0x0000–0x000D | Prozess & Threads | 14 | | 0x0100–0x0105 | Speicher | 6 | | 0x0200–0x0215 | Dateisystem & VFS | 22 | | 0x0300–0x0305 | I/O & Geräte | 6 | | 0x0400–0x040C | IPC & Synchronisation | 13 | | 0x0500–0x0504 | Zeit | 5 | | 0x0600–0x0609 | Netzwerk | 10 | | 0x0700–0x0708 | Sicherheit & Capabilities | 9 | | 0x0800–0x0812 | KI & Semantik + Wissensgraph | 19 | | 0x0900–0x090B | Lyra Agent Interface | 12 | | 0x0A00–0x0A05 | Debug & Telemetrie | 6 | | 0x0B00–0x0B09 | Task & Automatische Parallelität | 10 | | 0x0C00–0x0C04 | IOFS | 5 | | **Gesamt** | | **137** | Reservierte Bereiche: ''0x000E–0x00FF'', ''0x0106–0x01FF'', ''0x0216–0x02FF'', ''0x0813–0x08FF'', ''0x090C–0x09FF'', ''0x0D00–0xFFFF'' (zukünftige Kategorien). ---- ===== 6. Pledge-Promises ===== ''sys_pledge'' beschränkt dauerhaft die erlaubten Syscall-Klassen eines Prozesses. Einmal gesetzt, nie erweiterbar.


"stdio"   – read/write/poll auf bestehenden fds
"rpath"   – Dateisystem lesend öffnen/stat
"wpath"   – Dateisystem schreibend öffnen
"cpath"   – Dateien erzeugen/löschen
"exec"    – sys_spawn
"net"     – Socket-Syscalls (0x0600-0x0609)
"thread"  – sys_thread_spawn
"memory"  – sys_mmap / sys_mprotect
"device"  – sys_ioctl, sys_port_in/out
"ai"      – KI-Syscalls (0x0800-0x08FF)
"lyra"    – Lyra-Syscalls (0x0900-0x09FF)
"admin"   – privilegierte Syscalls (sys_mount, sys_setuid, ...)

Letzte Aktualisierung: 2026-06-09