# d3ara1n/halcyon architecture

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

- Interactive diagram: https://gitdiagram.com/d3ara1n/halcyon
- Repository: https://github.com/d3ara1n/halcyon

## Overview

##### Project Type and Purpose
- This is an educational, monolithic RV64 operating system (“eRhino”) written in Rust.
- It comprises:
- A boot‐time submodule layer (OpenSBI, U‑Boot, DTB parser)
- A kernel (“os/kernel”) with subsystems (MM, FS, IPC, scheduler, drivers, SBI interface)
- A shared Rust crate (“shared/”) used by both kernel and user space
- A user space stack (“user/”) including drivers, frameworks, a minimal runtime library (rinlib), and system binaries (fs, init, pm)
- Support for multiple platforms (QEMU virt, sifive_u, Kendryte K210, Renode)

##### File Structure Analysis
- Top‐level directories:
- os/: Kernel code + platform definitions (linker scripts, DTS)
- shared/: Common abstractions (calls, FAL, IPC, sync, time, etc.)
- user/:
– drivers/ (e.g., SPI)
– frameworks/ (libdrv, libfal, libsrv)
– rinlib/ (runtime support: threads, IPC, FS, RT)
– systems/ (userland binaries: fs, init, pm)
- submodules/: External repos (dtb_parser, opensbi, u‑boot)
- Kernel follows a layered, modular design: board abstraction → device drivers → core subsystems (MM, FS, task, IPC, timer, console) → SBI as lowest‐level interface

##### README Insights
- The README confirms:
- Design notes under notes/*.md (e.g., IPC, FS architecture)
- Build & run flows using Justfile with PLATFORM/​MODEL variables
- Current progress (IPC, FS, supported platforms)
- Userland relies on rinlib in lieu of std

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Firmware Layer
    subgraph "Firmware Layer" 
        direction TB
        OSBI["OpenSBI"]:::firmware
        UBOOT["U‑Boot"]:::firmware
        DTB["DTB Parser"]:::firmware
    end

    %% Kernel Layer
    subgraph "Kernel Layer" 
        direction TB
        KM["os/kernel/Cargo.toml"]:::kernel
        ENTRY["main.rs"]:::kernel
        BOARD["Board Abstraction"]:::kernel
        DEVIF["Device Drivers Interface"]:::kernel
        MM["Memory Management"]:::kernel
        FS["File System & FAL"]:::kernel
        TASK["Task Management"]:::kernel
        SCHED["Scheduler"]:::kernel
        IPC["IPC"]:::kernel
        TIMER["Timer Subsystem"]:::kernel
        RNG["RNG Subsystem"]:::kernel
        SBIIF["SBI Interface"]:::kernel
        SYNC["Synchronization"]:::kernel
        CONS["Console & Logging"]:::kernel
        TRAP["Trap Handling"]:::kernel
        PLAT["Platform Definitions"]:::kernel
    end

    %% Shared Library
    SHARED["Shared Crate"]:::shared

    %% User Space Layer
    subgraph "User Space Layer"
        direction TB
        RIN["rinlib (Runtime)"]:::user
        LIBDRV["libdrv"]:::user
        LIBFAL["libfal"]:::user
        LIBSRV["libsrv"]:::user
        UDRV["spi_sifive"]:::user
        USYS_FS["fs"]:::user
        USYS_INIT["init"]:::user
        USYS_PM["pm"]:::user
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        CPU["CPU Cores & MMU"]:::hardware
        MEMDEV["Memory"]:::hardware
        INTDEV["Interrupt Controller"]:::hardware
        SPIDEV["SPI Device"]:::hardware
        TMRDEV["Timer"]:::hardware
        CONDEV["Console Device"]:::hardware
    end

    %% Flows
    BootROM["Boot ROM"]:::hardware
    BootROM -->|boots| OSBI
    OSBI -->|loads| UBOOT
    UBOOT -->|parses DTB| DTB
    DTB -->|loads kernel| KM
    KM -->|entry| ENTRY

    ENTRY -->|init board| BOARD
    BOARD --> DEVIF
    DEVIF --> CPU
    DEVIF --> MEMDEV
    DEVIF --> INTDEV
    DEVIF --> SPIDEV
    DEVIF --> TMRDEV
    DEVIF --> CONDEV

    ENTRY --> MM
    ENTRY --> FS
    ENTRY --> TASK
    TASK --> SCHED
    TASK --> IPC
    ENTRY --> TIMER
    ENTRY --> RNG
    ENTRY --> SBIIF
    ENTRY --> SYNC
    ENTRY --> CONS
    ENTRY --> TRAP
    ENTRY --> PLAT

    %% Shared interactions
    SHARED -->|provides abstractions| ENTRY
    SHARED -->|provides abstractions| RIN

    %% Userland syscall
    RIN -->|syscall| ENTRY
    LIBDRV -->|uses rinlib| RIN
    LIBFAL -->|uses rinlib| RIN
    LIBSRV -->|uses rinlib| RIN
    UDRV -->|uses libdrv| LIBDRV
    USYS_FS -->|uses libfal| LIBFAL
    USYS_INIT -->|uses libsrv| LIBSRV
    USYS_PM -->|uses libsrv| LIBSRV

    %% Kernel ↔ Hardware via SBI calls
    SBIIF -->|SBI call| CPU
    SBIIF -->|SBI call| MEMDEV
    SBIIF -->|SBI call| INTDEV
    SBIIF -->|SBI call| SPIDEV
    SBIIF -->|SBI call| TMRDEV
    SBIIF -->|SBI call| CONDEV

    %% Click Events
    click OSBI "https://github.com/d3ara1n/halcyon/tree/master/submodules/opensbi"
    click UBOOT "https://github.com/d3ara1n/halcyon/tree/master/submodules/u-boot"
    click DTB "https://github.com/d3ara1n/halcyon/tree/master/submodules/dtb_parser"
    click KM "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/Cargo.toml"
    click ENTRY "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/main.rs"
    click BOARD "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/board.rs"
    click DEVIF "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/device.rs"
    click MM "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/mm.rs"
    click FS "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/fs.rs"
    click TASK "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/task.rs"
    click SCHED "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/task/sched.rs"
    click IPC "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/task/ipc.rs"
    click TIMER "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/timer.rs"
    click RNG "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/rng.rs"
    click SBIIF "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/sbi.rs"
    click SYNC "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/sync.rs"
    click CONS "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/console.rs"
    click TRAP "https://github.com/d3ara1n/halcyon/blob/master/os/kernel/src/trap.rs"
    click PLAT "https://github.com/d3ara1n/halcyon/tree/master/os/platforms/"
    click SHARED "https://github.com/d3ara1n/halcyon/tree/master/shared/src/"
    click RIN "https://github.com/d3ara1n/halcyon/tree/master/user/rinlib/src/"
    click LIBDRV "https://github.com/d3ara1n/halcyon/tree/master/user/frameworks/libdrv/src/"
    click LIBFAL "https://github.com/d3ara1n/halcyon/tree/master/user/frameworks/libfal/src/"
    click LIBSRV "https://github.com/d3ara1n/halcyon/tree/master/user/frameworks/libsrv/src/"
    click UDRV "https://github.com/d3ara1n/halcyon/blob/master/user/drivers/spi_sifive/src/main.rs"
    click USYS_FS "https://github.com/d3ara1n/halcyon/blob/master/user/systems/fs/src/main.rs"
    click USYS_INIT "https://github.com/d3ara1n/halcyon/blob/master/user/systems/init/src/main.rs"
    click USYS_PM "https://github.com/d3ara1n/halcyon/blob/master/user/systems/pm/src/main.rs"

    %% Styles
    classDef firmware fill:#bbbbbb,stroke:#888888,color:#000000;
    classDef kernel fill:#cce5ff,stroke:#3399ff,color:#000000;
    classDef shared fill:#d5f5e3,stroke:#27ae60,color:#000000;
    classDef user fill:#f9e79f,stroke:#d4ac0d,color:#000000;
    classDef hardware fill:#bbbbbb,stroke:#444444,color:#000000;
```
