====== Lyx OS – Erste Schritte ======

Diese Seite zeigt, wie man Lyx OS baut, in QEMU startet und ein erstes Ring-3-Programm schreibt. Voraussetzung sind Grundkenntnisse in der [[lyx_-_programmiersprache:start|Lyx-Sprache]] und einer Linux-Kommandozeile.

→ [[lyxos:start|Übersicht]] · [[lyxos:architektur|Architektur]] · [[lyxos:anwendungen|Anwendungen entwickeln]]

----

===== 1. Voraussetzungen =====

Alle benötigten Tools müssen im ''PATH'' verfügbar sein:

<code bash>
# Debian / Ubuntu
sudo apt install nasm qemu-system-x86 ovmf gdisk dosfstools mtools

# Compiler (muss bereits installiert sein)
lyxc --version   # erwartet: lyxc version 0.9.3B
</code>

^ Tool ^ Zweck ^
| ''nasm'' | UEFI-Bootloader aus boot.asm assemblieren |
| ''qemu-system-x86_64'' | LyxOS in einer virtuellen Maschine starten |
| ''ovmf'' | UEFI-Firmware für QEMU (OVMF_CODE.fd + OVMF_VARS.fd) |
| ''sgdisk'' (gdisk) | GPT-Partitionstabelle auf dem Disk-Image anlegen |
| ''mformat, mmd, mcopy'' (mtools) | FAT32-Partition befüllen |
| ''lyxc'' | Lyx-Kernel und Ring-3-Programme kompilieren |

----

===== 2. Repository einrichten =====

<code bash>
git clone https://github.com/lyxos/lyx-os.git   # oder eigenes Verzeichnis
cd lyx-os
</code>

Das Repository hat folgende Struktur:

<code>
lyx-os/
├── bootloader/          ← NASM-Bootloader (boot.asm), build.sh, run.sh
├── kernel/              ← Kernel-Module in Lyx (.lyx / .lyu)
├── shell/               ← Ring-3-Shell (shell.lyx)
├── examples/            ← Beispielprogramme für LyxOS
└── doku/                ← Interne Spezifikationen (syscalls.md, fahrplan.md)
</code>

----

===== 3. Kernel und Disk-Image bauen =====

<code bash>
bash bootloader/build.sh
</code>

Das Skript führt vier Schritte aus:

  - Assembliert ''BOOTX64.EFI'' aus ''bootloader/boot.asm'' (NASM, PE32+-Format)
  - Kompiliert alle Kernel-Module zu ''.lyu''-Units und linkt ''kernel.elf''
  - Erstellt ein 128-MB-Disk-Image (''lyx_boot.img'') mit GPT-Partitionstabelle und FAT32-EFI-Partition
  - Kopiert ''BOOTX64.EFI'' nach ''/EFI/BOOT/'' und ''kernel.elf'' in die Partition

Erwartete Ausgabe (gekürzt):

<code>
[1/4] Assembling bootloader...
      BOOTX64.EFI  10240 bytes
[2/4] Compiling kernel...
      kernel.elf   98304 bytes
[3/4] Building bootable disk image...
[4/4] Staging ESP directory...

Build complete.
  Disk image : bootloader/lyx_boot.img
Boot with:  bash bootloader/run.sh
</code>

----

===== 4. Lyx OS starten =====

<code bash>
bash bootloader/run.sh
</code>

QEMU startet mit 256 MB RAM, KVM-Beschleunigung und OVMF-Firmware. Kernel-Ausgaben erscheinen direkt im Terminal (COM1 → stdio).

==== Optionen ====

<code bash>
bash bootloader/run.sh --headless    # kein Grafikfenster (nur serielle Ausgabe)
bash bootloader/run.sh --no-kvm      # Software-Emulation ohne KVM (langsamerer, aber überall nutzbar)
</code>

==== Erwartete Ausgabe ====

<code>
Lyx OS v0.1 - Kernel running
PMM: init... free pages: 65432
VMM: identity map + CR3 load... CR3=0x200000 OK
Exceptions: IDT loaded (256 gates)
SMP: 4 CPUs detected, APs started
ATA: disk ready
FAT32: init OK
VFS: mounted
Keyboard: ready

Lyx Shell v0.1 - Ring-3 active
Exit.
</code>

Debug-Ausgaben werden zusätzlich nach ''/tmp/lyx_debugcon.txt'' geschrieben.

----

===== 5. Erstes eigenes Programm =====

Ring-3-Programme werden mit ''lyxc --target=lyxos'' kompiliert. Das Target löst alle Standard-Builtins (''PrintLn'', ''mmap'' usw.) auf LyxOS-Syscalls auf — keine libc-Abhängigkeit.

Erstelle ''hello.lyx'':

<code lyx>
fn main(): int64 {
    PrintLn("Hallo von Ring-3!");
    return 0;
}
</code>

Kompilieren:

<code bash>
lyxc --target=lyxos hello.lyx -o hello.elf
</code>

Das Binary ''hello.elf'' ist ein ELF64-Executable das direkt auf LyxOS läuft. Es verwendet ausschließlich den ''sys_write''- und ''sys_exit''-Syscall — kein Userspace-Linking gegen Bibliotheken.

<box gh>
> **Hinweis:** Die Shell in M4 startet ''hello.elf'' noch nicht automatisch. Das vollständige Programm-Laden aus dem Dateisystem ist Teil von M5. Für jetzt: das Binary in ''kernel.elf'' integrieren und beim Systemstart aufrufen.
</box>

==== Direkter Syscall aus Lyx ====

Wer Syscalls direkt nutzen möchte, ohne Builtins:

<code lyx>
// Syscall-Nummern als Konstanten
con SYS_WRITE: int64 := 0x0203;
con FD_STDOUT: int64 := 1;

fn WriteLn(msg: pchar) {
    // sys_write(fd, buf, len)  →  rax=Fehler, rdx=bytes
    var msg_len: int64 := StrLen(msg);
    // Lyx --target=lyxos mappt sys_write auf das native syscall-Gate
    var err: int64 := 0;
    var written: int64 := 0;
    // Inline-Syscall via Compiler-Builtin (verfügbar ab M5):
    // (err, written) := syscall(SYS_WRITE, FD_STDOUT, msg, msg_len);
}
</code>

→ Vollständige Syscall-Referenz: [[lyxos:syscalls|Syscall-ABI v1.0]]

----

===== 6. Debugging =====

==== Serielle Ausgabe ====

''PrintLn'' und ''PrintStr'' aus Kernel- und Ring-3-Code erscheinen beide auf COM1 → Terminal. Kein separates Debug-Interface nötig.

==== Debug-Konsole ====

''PrintStr'' an einen speziellen Debug-Port schreibt nach ''/tmp/lyx_debugcon.txt'':

<code bash>
tail -f /tmp/lyx_debugcon.txt
</code>

==== QEMU Monitor ====

Im laufenden QEMU: ''Ctrl-Alt-2'' wechselt in den QEMU-Monitor. Nützliche Befehle:

<code>
info mem          # aktueller Page-Table-Dump
info registers    # CPU-Registerstand
x/10i $pc         # Disassembly ab aktuellem Instruction Pointer
</code>

Letzte Aktualisierung: 2026-06-09