# sysprog21/linmo architecture

> Architecture diagram of the GitHub repository sysprog21/linmo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sysprog21/linmo
- Repository: https://github.com/sysprog21/linmo

## Overview

##### Project type and purpose
- Linmo is a monolithic, educational, multi-tasking OS kernel for RV32I (RISC-V).
- It provides preemptive/cooperative scheduling, a minimal C library, IPC primitives, dynamic memory, and a HAL to abstract hardware.
- Example applications live in `app/` and run on QEMU.

##### File structure
Top-level folders:
- `arch/riscv/` – RISC-V HAL: startup code, CSR handling, PMP, linker script.
- `kernel/` – core scheduler, task management, IPC (mutex, semaphores, pipes), syscalls.
- `lib/` & `include/lib/` – minimal C library implementation (`malloc`, `printf`, etc.).
- `app/` – user programs linking against `liblinmo.a`.
- `include/` – public/kernel headers (`syscall.h`, task APIs, IPC APIs).
- `Makefile`, `mk/` – build system that produces `liblinmo.a`, example binaries, and QEMU run targets.

##### README for architecture insights
- “Hardware Abstraction Layer (HAL)” – separates arch-specific from portable code.
- “Shared single address space” – all tasks plus kernel share memory.
- “Scheduler” – priority‐based round-robin, preemptive via timer interrupts in HAL.
- IPC primitives – implemented inside the kernel layer.

##### Main components and relationships
– Hardware (RISC-V CPU + memory + timer + PMP unit)
– HAL layer (`arch/riscv/*.c`, `arch/riscv/*.h`)
– Kernel core (`kernel/*.c`)
– C library (`lib/*.c`, `include/lib/*.h`)
– System Call / IPC interface (`include/sys/*`, `kernel/syscall.c`)
– Applications (`app/*.c`)
– Build & Test tools (Makefile, scripts, QEMU emulator)
b. Interactions:
– Apps → link → C library → invoke syscalls
– Syscalls → trap/interrupt → kernel dispatcher → kernel services (task, IPC, mem)
– Kernel → calls HAL for context switch, interrupt handling, hardware config (CSR, PMP)
– HAL → toggles hardware registers, sets up timer interrupts
– Build system → cross-compiles code → produces `liblinmo.a` and application binaries → QEMU
c. Architectural patterns:
– Layered monolithic kernel: HAL at the bottom, kernel services in the middle, C library & system calls on top, apps at the highest level.
– Single address space—no MMU, but optional PMP memory protection.
– Preemptive/cooperative scheduler implemented via HAL-driven timer interrupts.
d. Key technologies & frameworks:
– RISC-V RV32I, QEMU
– GNU toolchain (`riscv-none-elf-gcc`)
– Makefile + `mk/common.mk`
– C codebase, no external dependencies

##### Detail checklist (do not omit)
- All top-level modules (`arch/riscv`, `kernel`, `lib`, `app`)
- Build artifacts (`liblinmo.a`, Makefile targets, QEMU emulator)
- Memory model: heap, per-task stacks, shared address space
- IPC primitives as sub-components of kernel (mutexes, semaphores, pipes, mqueues)
- Scheduling modes (cooperative vs preemptive) as configuration in HAL/kernel

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware" 
        HW["RISC-V CPU, Timer, Memory, PMP Unit"]:::hardware
    end
    click HW "https://github.com/sysprog21/linmo/tree/main/arch/riscv/"

    %% HAL Layer
    subgraph "HAL (arch/riscv)" 
        HAL["HAL Layer"]:::hardware
    end
    click HAL "https://github.com/sysprog21/linmo/blob/main/arch/riscv/hal.c"

    %% Kernel Layer
    subgraph "Kernel Core & Services"
        SC["Scheduler & Task Management"]:::kernel
        IPC["IPC Primitives\n(mutex, semaphores, pipes, mqueues)"]:::kernel
        MEM["PMP Integration (Memory Protection)"]:::kernel
        SYSC["Syscall Dispatcher & Interface"]:::kernel
        UTIL["Utilities & Logging"]:::kernel
    end
    click SC "https://github.com/sysprog21/linmo/blob/main/kernel/main.c"
    click IPC "https://github.com/sysprog21/linmo/blob/main/kernel/mutex.c"
    click MEM "https://github.com/sysprog21/linmo/blob/main/kernel/memprot.c"
    click SYSC "https://github.com/sysprog21/linmo/blob/main/kernel/syscall.c"
    click UTIL "https://github.com/sysprog21/linmo/blob/main/kernel/logger.c"

    %% C Library Layer
    subgraph "C Library & Syscall API"
        CLIB["C Library (malloc, printf, etc.)"]:::lib
    end
    click CLIB "https://github.com/sysprog21/linmo/blob/main/lib/malloc.c"

    %% Applications Layer
    subgraph "Applications (app/)"
        APP["User-level Programs"]:::app
    end
    click APP "https://github.com/sysprog21/linmo/blob/main/app/hello.c"

    %% Build & Test Layer
    subgraph "Build System & Emulation"
        BS["Makefile, mk scripts, QEMU Targets"]:::tool
    end
    click BS "https://github.com/sysprog21/linmo/tree/main/Makefile"

    %% Shared Memory Model
    MEMO(("Shared Address Space\n(heap, stacks)")):::memory

    %% Interactions
    APP -->|"links against"| CLIB
    CLIB -->|"syscall() calls"| SYSC
    SYSC -->|"trap/dispatch"| SC
    SC -->|"invokes HAL for context switch"| HAL
    HAL -->|"timer IRQ, CSR/PMP config"| SC
    HAL -->|"configures PMP registers"| MEM
    HW -->|"timer interrupt"| HAL
    HW -->|"hardware registers (CSR/PMP)"| HAL
    BS -->|"builds"| CLIB
    BS -->|"builds"| SYSC
    BS -->|"runs on"| HW

    %% Memory model integration
    MEMO -.-> APP
    MEMO -.-> CLIB
    MEMO -.-> SYSC
    MEMO -.-> SC
    MEMO -.-> MEM

    %% Styles
    classDef hardware fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef kernel fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef lib fill:#fffd82,stroke:#333,stroke-width:1px
    classDef app fill:#ffadad,stroke:#333,stroke-width:1px
    classDef tool fill:#cdb4db,stroke:#333,stroke-width:1px
    classDef memory fill:#d0f4de,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
