# 0bvdnt/obv-os architecture

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

- Interactive diagram: https://gitdiagram.com/0bvdnt/obv-os
- Repository: https://github.com/0bvdnt/obv-os

## Overview

##### Project type and purpose
- obv-OS is a minimal, educational, monolithic RISC-V operating system.
- Each folder under `learning-basics/` is a self-contained module demonstrating one OS concept (kernel entry, console output, memory management, exception handling, context switching, scheduler).

##### File structure
- Top level:
- `.gitignore`, `README.md`
- `learning-basics/`: contains one directory per learning module
- Module directory (e.g. `memory-allocation/`):
- `kernel.c`, `common.c`, `common.h`, `kernel.h` – C source and headers
- `kernel.ld` – linker script
- `opensbi-riscv32-generic-fw_dynamic.bin` – OpenSBI firmware
- `run.sh` – build & QEMU launch script
- `README.md` – module description
- No separate “frontend/backend” – it's a bare-metal, single-executable kernel.

##### README for additional insights
- The root README enumerates modules and prerequisites (RISC-V toolchain, QEMU, OpenSBI).
- Emphasis on incremental layering: simple kernel → I/O → memory → exceptions → multitasking.

- A tree with 3 levels:
− Root
└ learning-basics
├ implementing-simple-kernel
├ output-from-the-kernel
├ memory-allocation
├ exception-handling
├ process-control-and-context-switching
└ process-scheduler-and-exception-handler
- Within each module, list key files (.c/.h, .ld, firmware, run script).

1. Host Machine (build environment)
– RISC-V Toolchain
– llvm-nm / objdump
2. Emulator Layer
– QEMU `virt`
– OpenSBI firmware
3. Kernel Image
– Entry & startup (implemented in `kernel.c` & `kernel.ld`)
- Console I/O (functions: putchar(), printf(), SBI calls)
- Memory Manager (bump allocator: alloc_pages(), free_pages())
- Exception Handler (trap vector setup, trap_frame struct, panic())
- Process Control (PCB struct, context (registers) struct)
- Scheduler (switch_context(), round-robin logic)
4. Data flows
– Build scripts → compilers → link via `kernel.ld` → QEMU loads OpenSBI + kernel
– Kernel ↔ SBI → Console
– Kernel ↔ physical memory (via page allocator)
– Kernel ↔ CPU (traps & context switches)

- PCB
– Fields: register array, stack pointer, state
- trap_frame
– Fields: saved registers
- Allocator
– Functions: alloc_pages(), init_allocator()
- Context Switch
– Functions: switch_context(old_pcb, new_pcb)
- Console
– Functions: sbi_call(), putchar(), printf()
- Relationships
– Scheduler “owns” a list of PCB instances
– Exception Handler uses trap_frame to save/restore registers
– Allocator is called by kernel startup and by processes

##### Don’t overthink – break the kernel into as many logical pieces as possible
- Each `learning-basics` module becomes a layer in your monolithic design view.

- How code is organized on disk
- How the build & runtime environments interact
- How the kernel’s internal modules and data structures collaborate at runtime
- Which source files implement each subsystem

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Directory Structure
    subgraph "Directory Structure" 
        direction TB
        Root["/ (repo root)"]:::root
        LB["learning-basics/"]:::dir
        Root --> LB
        subgraph "Modules" 
            direction TB
            M1["implementing-simple-kernel/"]:::dir
            M2["output-from-the-kernel/"]:::dir
            M3["memory-allocation/"]:::dir
            M4["exception-handling/"]:::dir
            M5["process-control-and-context-switching/"]:::dir
            M6["process-scheduler-and-exception-handler/"]:::dir
        end
        LB --> M1
        LB --> M2
        LB --> M3
        LB --> M4
        LB --> M5
        LB --> M6

        %% Files inside one module (example for each)
        subgraph "Files in each module" 
            direction TB
            F_c["kernel.c"]:::file
            F_cc["common.c"]:::file
            F_ch["common.h"]:::file
            F_kh["kernel.h"]:::file
            F_ld["kernel.ld"]:::file
            F_fw["opensbi-riscv32-generic-fw_dynamic.bin"]:::file
            F_sh["run.sh"]:::file
            F_md["README.md"]:::file
        end
        M1 --> F_c
        M1 --> F_cc
        M1 --> F_ch
        M1 --> F_ld
        M1 --> F_fw
        M1 --> F_sh
        M1 --> F_md
        M2 --> F_c
        M2 --> F_cc
        M2 --> F_ch
        M2 --> F_ld
        M2 --> F_fw
        M2 --> F_sh
        M2 --> F_md
        M3 --> F_c
        M3 --> F_cc
        M3 --> F_ch
        M3 --> F_ld
        M3 --> F_fw
        M3 --> F_sh
        M3 --> F_md
        M4 --> F_c
        M4 --> F_cc
        M4 --> F_ch
        M4 --> F_ld
        M4 --> F_fw
        M4 --> F_sh
        M4 --> F_md
        M5 --> F_c
        M5 --> F_cc
        M5 --> F_ch
        M5 --> F_ld
        M5 --> F_fw
        M5 --> F_sh
        M5 --> F_md
        M6 --> F_c
        M6 --> F_cc
        M6 --> F_ch
        M6 --> F_ld
        M6 --> F_fw
        M6 --> F_sh
        M6 --> F_md
    end

    %% Component (Class) Diagram
    subgraph "Kernel Component Diagram"
        direction TB
        %% Data Structures
        PCB["PCB|+ regs[]:uint32_t<br>+ sp:uint32_t<br>+ state:int"]:::data
        TF["trap_frame|+ regs_saved[]:uint32_t"]:::data
        Alloc["Allocator|+ init():void<br>+ alloc_pages():void<br>+ free_pages():void"]:::data
        CSW["ContextSwitch|+ switch_context(old, new):void"]:::data
        Console["Console|+ sbi_call():int<br>+ putchar(c):void<br>+ printf(fmt,...):void"]:::data

        %% Subsystems
        ConsoleSS["Console I/O"]:::subsys
        MemSS["Memory Manager"]:::subsys
        EHSS["Exception Handler"]:::subsys
        PCSS["Process Control"]:::subsys
        SCHSS["Scheduler"]:::subsys

        %% Relationships
        ConsoleSS -->|uses| Console
        MemSS -->|uses| Alloc
        EHSS -->|uses| TF
        PCSS -->|manages| PCB
        SCHSS -->|owns list of| PCB
        SCHSS -->|calls| CSW
        EHSS -->|restores via| CSW
    end

    %% Click Events for modules
    click M1 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/implementing-simple-kernel"
    click M2 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/output-from-the-kernel"
    click M3 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/memory-allocation"
    click M4 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/exception-handling"
    click M5 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/process-control-and-context-switching"
    click M6 "https://github.com/0bvdnt/obv-os/tree/main/learning-basics/process-scheduler-and-exception-handler"

    classDef root fill:#A9CCE3,stroke:#1B4F72,color:#1B2631
    classDef dir fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef file fill:#D5DBDB,stroke:#566573,color:#1B2631
    classDef data fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef subsys fill:#D5F5E3,stroke:#239B56,color:#1E8449
```
