# julien-cpsn/retos architecture

> Architecture diagram of the GitHub repository julien-cpsn/retos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/julien-cpsn/retos
- Repository: https://github.com/julien-cpsn/retos

## Overview

##### Main Components
- Host & Hypervisor
– QEMU x86_64 (BIOS/UEFI)
– Host‐side network (TAP interface created by create_tap_interface.sh)
- Bootloader
– Invokes kernel binary (src/bin/qemu_bios.rs or qemu_uefi.rs)
– Sets CPU to 64-bit mode, loads kernel image
- Kernel Core
– Initialization: GDT, IDT, paging (kernel/src/interrupts, kernel/src/memory)
– Memory manager & allocator (heap_allocator.rs, allocator.rs)
– Scheduler/task executor & async runtime (kernel/src/task/executor.rs, task.rs)
– Logging & clock (logger.rs, clock.rs)
- Hardware Abstraction & Drivers
– PCI & ACPI enumeration (pci.rs, acpi.rs)
– Interrupt controllers (APIC, PIC modules)
– Device drivers:
· NICs: E1000, RTL8139 (kernel/src/devices/drivers)
· USB: xHCI (kernel/src/devices/xhci.rs)
· PS/2 keyboard (keyboard.rs under task or driver)
- Terminal & CLI
– Terminal abstraction (kernel/src/terminal/terminal.rs)
– Embedded‐CLI framework and built-in commands (clear, echo, lspci, scanpci, ps, top, uptime, shutdown)
- Utilities & Tests
– ping.py (host‐side network test)
– create_tap_interface.sh (network bridge setup)

##### Relationships & Data Flows
– Show Kernel Core initializing subsystems in sequence (GDT/IDT → Paging → Memory Allocator → Scheduler).
– Indicate interrupt flow: hardware → PIC/APIC → IDT → interrupt handlers in kernel.
– Show the Scheduler/Executor dispatching tasks (keyboard input, CLI commands, network packet I/O).
– Represent the Terminal subsystem atop drivers, issuing commands that invoke kernel services.
– For networking, show QEMU’s virtual NIC → host TAP interface → driver (E1000/RTL8139) → future TCP/IP stack.

##### Architectural Patterns & Principles
– Layered design: Bootloader → Kernel Core → HAL (drivers) → User Interface (CLI).
– Modularity via Rust crates: separate modules for memory, interrupts, devices, tasks, terminal.
– Asynchronous tasks model: executor schedules I/O and command tasks.
– Use of external crates: x86_64 for low‐level CPU structures, bootloader crate, embedded‐cli‐rs, goolog.

##### Technologies & Frameworks
– Rust / Cargo ecosystem (.cargo/config.toml, Cargo.toml)
– QEMU virtualization (BIOS/UEFI)
– Rust OS‐dev crates: x86_64, bootloader, pic8259, pci_types, embedded‐cli‐rs, goolog
– Network TAP interface (create_tap_interface.sh)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host and Utilities
    subgraph "Host & Hypervisor"
        QEMU["QEMU x86_64"]:::host
        TAP_IF["TAP Interface"]:::host
    end
    subgraph "Host Utilities"
        CTAP["create_tap_interface.sh"]:::util
        PING["ping.py"]:::util
    end
    click CTAP "https://github.com/julien-cpsn/retos/blob/main/create_tap_interface.sh"
    click PING "https://github.com/julien-cpsn/retos/blob/main/ping.py"

    %% Hardware Layer
    subgraph "Hardware Layer"
        CPU["CPU (x86_64)"]:::hw
        MEM["System Memory"]:::hw
        PCI["PCI Bus"]:::hw
        IO["I/O Bus"]:::hw
        APIC_HW["APIC/PIC Controllers"]:::hw
        NIC_HW["Virtual NIC"]:::hw
    end

    %% Bootloader Layer
    subgraph "Bootloader" 
        BIOS_ENTRY["BIOS Entry (qemu_bios.rs)"]:::boot
        UEFI_ENTRY["UEFI Entry (qemu_uefi.rs)"]:::boot
    end
    click BIOS_ENTRY "https://github.com/julien-cpsn/retos/blob/main/src/bin/qemu_bios.rs"
    click UEFI_ENTRY "https://github.com/julien-cpsn/retos/blob/main/src/bin/qemu_uefi.rs"

    %% Kernel Core Layer
    subgraph "Kernel Core" 
        K_MAIN["Kernel Main (main.rs)"]:::kernel
        K_LIB["Kernel Lib (lib.rs)"]:::kernel

        subgraph "Initialization"
            GDT["GDT Setup"]:::kernel
            IDT["IDT & Interrupt Setup"]:::kernel
            PAGING["Paging & Tables"]:::kernel
        end

        subgraph "Memory Subsystem"
            ALLOC["Allocator"]:::kernel
            HEAP["Heap Allocator"]:::kernel
        end

        subgraph "Task & Async"
            EXEC["Async Executor"]:::kernel
            TASK["Task Scheduler"]:::kernel
        end

        subgraph "Logging & Clock"
            LOG["Logger"]:::kernel
            CLOCK["Clock"]:::kernel
        end
    end
    click K_MAIN "https://github.com/julien-cpsn/retos/blob/main/kernel/src/main.rs"
    click K_LIB "https://github.com/julien-cpsn/retos/blob/main/kernel/src/lib.rs"
    click GDT "https://github.com/julien-cpsn/retos/blob/main/kernel/src/interrupts/gdt.rs"
    click IDT "https://github.com/julien-cpsn/retos/blob/main/kernel/src/interrupts/idt.rs"
    click PAGING "https://github.com/julien-cpsn/retos/blob/main/kernel/src/memory/pagination.rs"
    click ALLOC "https://github.com/julien-cpsn/retos/blob/main/kernel/src/memory/allocator.rs"
    click HEAP "https://github.com/julien-cpsn/retos/blob/main/kernel/src/memory/heap_allocator.rs"
    click EXEC "https://github.com/julien-cpsn/retos/blob/main/kernel/src/task/executor.rs"
    click TASK "https://github.com/julien-cpsn/retos/blob/main/kernel/src/task/task.rs"
    click LOG "https://github.com/julien-cpsn/retos/blob/main/kernel/src/logger.rs"
    click CLOCK "https://github.com/julien-cpsn/retos/blob/main/kernel/src/clock.rs"

    %% HAL & Device Drivers
    subgraph "Device Abstraction & Drivers"
        PCI_ENUM["PCI Enumeration"]:::driver
        ACPI_ENUM["ACPI Enumeration"]:::driver
        subgraph "Interrupt Controllers"
            APIC["APIC Driver"]:::driver
            PIC["PIC Driver"]:::driver
        end
        subgraph "Network Drivers"
            E1000["E1000"]:::driver
            RTL8139["RTL8139"]:::driver
        end
        XHCI["USB xHCI"]:::driver
        KB_DEV["PS/2 Keyboard"]:::driver
        FB["Framebuffer & Printer"]:::driver
    end
    click PCI_ENUM "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/pci.rs"
    click ACPI_ENUM "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/acpi.rs"
    click APIC "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/pic/apic.rs"
    click PIC "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/pic/pic.rs"
    click E1000 "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/drivers/e1000.rs"
    click RTL8139 "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/drivers/rtl8139.rs"
    click XHCI "https://github.com/julien-cpsn/retos/blob/main/kernel/src/devices/xhci.rs"
    click KB_DEV "https://github.com/julien-cpsn/retos/blob/main/kernel/src/task/keyboard.rs"
    click FB "https://github.com/julien-cpsn/retos/blob/main/kernel/src/printer/buffer.rs"

    %% Terminal & CLI Layer
    subgraph "Terminal & CLI"
        TERM["Terminal Abstraction"]:::cli
        CLI_ENG["CLI Engine"]:::cli
        subgraph "Built-in Commands"
            CMD_CLEAR["clear"]:::cli
            CMD_ECHO["echo"]:::cli
            CMD_KB["keyboard"]:::cli
            CMD_LSPCI["lspci"]:::cli
            CMD_SCANPCI["scanpci"]:::cli
            CMD_PS["ps"]:::cli
            CMD_TOP["top"]:::cli
            CMD_UP["uptime"]:::cli
            CMD_SHUT["shutdown"]:::cli
        end
    end
    click TERM "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/terminal.rs"
    click CLI_ENG "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/cli.rs"
    click CMD_CLEAR "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/clear.rs"
    click CMD_ECHO "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/echo.rs"
    click CMD_KB "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/keyboard.rs"
    click CMD_LSPCI "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/lspci.rs"
    click CMD_SCANPCI "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/scanpci.rs"
    click CMD_PS "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/ps.rs"
    click CMD_TOP "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/top.rs"
    click CMD_UP "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/uptime.rs"
    click CMD_SHUT "https://github.com/julien-cpsn/retos/blob/main/kernel/src/terminal/commands/shutdown.rs"

    %% Cargo & Toolchain
    CARGO_ROOT["Cargo.toml"]:::config
    CARGO_CROOT[".cargo/config.toml"]:::config
    CARGO_KROOT["kernel/Cargo.toml"]:::config
    CARGO_KCONF["kernel/.cargo/config.toml"]:::config

    click CARGO_ROOT "https://github.com/julien-cpsn/retos/blob/main/Cargo.toml"
    click CARGO_CROOT "https://github.com/julien-cpsn/retos/blob/main/.cargo/config.toml"
    click CARGO_KROOT "https://github.com/julien-cpsn/retos/blob/main/kernel/Cargo.toml"
    click CARGO_KCONF "https://github.com/julien-cpsn/retos/blob/main/kernel/.cargo/config.toml"

    %% Connections
    CPU --> BIOS_ENTRY
    CPU --> UEFI_ENTRY
    BIOS_ENTRY --> K_MAIN
    UEFI_ENTRY --> K_MAIN
    K_MAIN --> GDT --> IDT --> PAGING
    PAGING --> ALLOC --> HEAP
    HEAP --> EXEC --> TASK
    TASK --> LOG
    TASK --> CLOCK
    TASK --> TERM
    PCI --> PCI_ENUM --> XHCI
    PCI --> PCI_ENUM --> E1000
    PCI --> PCI_ENUM --> RTL8139
    PCI --> ACPI_ENUM
    APIC_HW --> APIC --> IDT
    APIC_HW --> PIC --> IDT
    NIC_HW --> E1000 --> TASK
    NIC_HW --> RTL8139 --> TASK
    TAP_IF --> NIC_HW
    QEMU --> NIC_HW
    TERM --> CLI_ENG
    CLI_ENG --> CMD_CLEAR
    CLI_ENG --> CMD_ECHO
    CLI_ENG --> CMD_KB
    CLI_ENG --> CMD_LSPCI
    CLI_ENG --> CMD_SCANPCI
    CLI_ENG --> CMD_PS
    CLI_ENG --> CMD_TOP
    CLI_ENG --> CMD_UP
    CLI_ENG --> CMD_SHUT

    CTAP --> TAP_IF
    PING --> NIC_HW

    %% Styles
    classDef host fill:#d3e5ff,stroke:#4a90e2,stroke-width:1px
    classDef util fill:#e0e0e0,stroke:#757575,stroke-width:1px
    classDef hw fill:#f0f4c3,stroke:#cddc39,stroke-width:1px
    classDef boot fill:#bbdefb,stroke:#2196f3,stroke-width:1px
    classDef kernel fill:#c8e6c9,stroke:#4caf50,stroke-width:1px
    classDef driver fill:#ffe0b2,stroke:#ff9800,stroke-width:1px
    classDef cli fill:#e1bee7,stroke:#9c27b0,stroke-width:1px
    classDef config fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px
```
