# archisman-mridha/operating-system architecture

> Architecture diagram of the GitHub repository archisman-mridha/operating-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/archisman-mridha/operating-system
- Repository: https://github.com/archisman-mridha/operating-system

## Overview

##### Project type and purpose
- From the file tree and README, this “Arno” project is an educational, monolithic operating-system kernel written in Rust for RISC-V.
- It includes:
- A low-level boot/entry (assembly) and linker script (“linker.ld”).
- Core kernel subsystems (memory, process, drivers, filesystem, locks).
- RISC-V support under “src/arch/riscv” and QEMU integration.
- “primitives” folder containing CPU models/emulators in Rust, TypeScript, and Verilog.

##### File structure
- Top-level:
- Cargo.toml, build.rs, shell.nix, linker.ld → build and toolchain setup.
- src/asm, src/start.rs, src/main.rs → boot and entry points.
- src/arch/riscv → architecture-specific code (modes, registers, QEMU glue).
- src/drivers → PLIC (interrupt controller), UART.
- src/memory → virtual/physical addressing, allocator (buddy, list), page tables.
- src/fs → disk abstraction, block cache.
- src/process → process struct, CPU/core management, scheduler.
- src/locks → spinlocks and sleeplocks.
- primitives:
- riscv-emulator in Rust under primitives/riscv-emulator.
- riscv-cpu in TypeScript and Verilog.

##### README insights
- Confirms this is a kernel running on RISC-V, using QEMU or custom CPU primitives.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Toolchain Layer
    subgraph "Build & Toolchain" 
        direction TB
        RT["rust-toolchain.toml"]:::build
        SN["shell.nix"]:::build
        BS["build.rs"]:::build
        LN["linker.ld"]:::boot
    end

    %% Bootloader Layer
    subgraph "Bootloader Layer" 
        direction TB
        AE["Assembly Entry (entry.S)"]:::boot
        SR["src/start.rs"]:::boot
        MR["src/main.rs"]:::kernel
    end

    %% Kernel Layer
    subgraph "Kernel Layer"
        direction TB
        subgraph "Arch Layer (RISC-V)"
            direction TB
            AR["src/arch/riscv/mod.rs"]:::kernel
            MO["modes & privileges"]:::kernel
            QM["QEMU Glue"]:::kernel
            CSR["CSR Registers"]:::kernel
        end
        subgraph "Memory Management"
            direction TB
            PA["physical.rs"]:::kernel
            VA["virtual.rs"]:::kernel
            AL["allocator.rs"]:::kernel
            PT["page_table"]:::kernel
        end
        subgraph "Process & Scheduling"
            direction TB
            PRC["process.rs"]:::kernel
            CORE["core & cpu.rs"]:::kernel
            SCH["manager.rs"]:::kernel
        end
        subgraph "Filesystem"
            direction TB
            DK["disk.rs"]:::kernel
            BC["bcache.rs"]:::kernel
        end
        subgraph "Drivers"
            direction TB
            PLIC["plic.rs"]:::kernel
            UART["uart.rs"]:::kernel
        end
        subgraph "Locks"
            direction TB
            SL["spinlock.rs"]:::kernel
            SLL["sleeplock.rs"]:::kernel
        end
    end

    %% Hardware/Emulation Layer
    subgraph "Hardware/Emulation"
        direction TB
        CPU_HW["CPU Core (Verilog ALU)"]:::hardware
        EMU_RUST["Rust Emulator"]:::hardware
        EMU_TS["TS Emulator"]:::hardware
        MMU["MMU / Physical Memory"]:::hardware
        PLIC_HW["PLIC"]:::hardware
        UART_HW["UART Device"]:::hardware
        DISK_HW["Disk Block Device"]:::hardware
    end

    %% Connections
    EMU_RUST -->|runs boot code| AE
    EMU_TS -->|runs boot code| AE
    CPU_HW -->|fetches| AE
    AE -->|"calls"| SR
    SR -->|"jumps to"| MR
    MR -->|"initializes"| AR
    MR -->|"initializes"| PA
    MR -->|"initializes"| VA
    MR -->|"initializes"| AL
    MR -->|"initializes"| PT
    MR -->|"sets up"| PRC
    MR -->|"starts"| SCH
    MR -->|"mounts"| DK
    MR -->|"initializes"| BC
    MR -->|"registers"| PLIC
    MR -->|"initializes"| UART
    MR -->|"initializes"| SL
    MR -->|"initializes"| SLL

    PLIC -->|interrupts| MR
    UART -->|I/O| MR
    DK -->|read/write| BC
    BC -->|blocks| DK
    AL -->|alloc pages| PA
    PA -->|physical memory| MMU
    VA -->|virtual memory| MMU
    EMU_RUST -->|provides| MMU
    EMU_TS -->|provides| MMU
    CPU_HW -->|connects| MMU
    PLIC -->|hardware| PLIC_HW
    UART -->|hardware| UART_HW
    DK -->|hardware| DISK_HW

    RT -->|configures| BS
    SN -->|provides| BS
    BS -->|generates| MR
    LN -->|links| MR

    %% Click events
    click AE "https://github.com/archisman-mridha/operating-system/blob/main/src/asm/entry.S"
    click LN "https://github.com/archisman-mridha/operating-system/blob/main/linker.ld"
    click BS "https://github.com/archisman-mridha/operating-system/blob/main/build.rs"
    click RT "https://github.com/archisman-mridha/operating-system/blob/main/rust-toolchain.toml"
    click SN "https://github.com/archisman-mridha/operating-system/blob/main/shell.nix"
    click SR "https://github.com/archisman-mridha/operating-system/blob/main/src/start.rs"
    click MR "https://github.com/archisman-mridha/operating-system/blob/main/src/main.rs"
    click AR "https://github.com/archisman-mridha/operating-system/blob/main/src/arch/riscv/mod.rs"
    click MO "https://github.com/archisman-mridha/operating-system/blob/main/src/arch/riscv/modes.rs"
    click QM "https://github.com/archisman-mridha/operating-system/blob/main/src/arch/riscv/qemu/mod.rs"
    click CSR "https://github.com/archisman-mridha/operating-system/tree/main/src/arch/riscv/registers/"
    click PA "https://github.com/archisman-mridha/operating-system/blob/main/src/memory/address/physical.rs"
    click VA "https://github.com/archisman-mridha/operating-system/blob/main/src/memory/address/virtual.rs"
    click AL "https://github.com/archisman-mridha/operating-system/blob/main/src/memory/allocator/allocator.rs"
    click PT "https://github.com/archisman-mridha/operating-system/blob/main/src/memory/page_table/entry.rs"
    click PRC "https://github.com/archisman-mridha/operating-system/blob/main/src/process/process.rs"
    click CORE "https://github.com/archisman-mridha/operating-system/blob/main/src/process/core.rs"
    click SCH "https://github.com/archisman-mridha/operating-system/blob/main/src/process/manager.rs"
    click DK "https://github.com/archisman-mridha/operating-system/blob/main/src/fs/disk.rs"
    click BC "https://github.com/archisman-mridha/operating-system/blob/main/src/fs/bcache.rs"
    click PLIC "https://github.com/archisman-mridha/operating-system/blob/main/src/drivers/plic.rs"
    click UART "https://github.com/archisman-mridha/operating-system/blob/main/src/drivers/uart.rs"
    click SL "https://github.com/archisman-mridha/operating-system/blob/main/src/locks/spinlock.rs"
    click SLL "https://github.com/archisman-mridha/operating-system/blob/main/src/locks/sleeplock.rs"
    click EMU_RUST "https://github.com/archisman-mridha/operating-system/blob/main/primitives/riscv-emulator/src/main.rs"
    click EMU_TS "https://github.com/archisman-mridha/operating-system/blob/main/primitives/riscv-cpu/typescript/index.ts"
    click CPU_HW "https://github.com/archisman-mridha/operating-system/blob/main/primitives/riscv-cpu/verilog/ALU.v"

    %% Styles
    classDef hardware fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef boot fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef kernel fill:#A8E6A3,stroke:#333,stroke-width:1px
    classDef build fill:#F7C27D,stroke:#333,stroke-width:1px
```
