# hamdannawaz582/picos architecture

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

- Interactive diagram: https://gitdiagram.com/hamdannawaz582/picos
- Repository: https://github.com/hamdannawaz582/picos

## Overview

##### Project Type and Purpose
- PicOS is a monolithic, microcontroller-based OS targeting the RP2040 (Raspberry Pi Pico).
- It provides basic kernel services (task scheduler, inter-task queues, exceptions, syscalls) and a filesystem (via littlefs).
- The ProjectTemplate folder shows how user applications are built on top of this kernel.

##### File Structure
- Top-level build files:
– CMakeLists.txt (primary build orchestrator)
– .gitmodules (pulls in external/littlefs)
- Kernel source:
– OS.c, defs.h, elf.h, proc.h, scheduler.h, queues.h, ksvc.h
– exceptions.S, exceptions.h (interrupt and fault handlers)
– SVC.h (supervisor call interface)
- External components:
– external/littlefs (filesystem library)
– pico_sdk_import.cmake (hooks the Pico SDK)
- ProjectTemplate:
– linkerscript.ld (memory layout for RP2040)
– main.c (example user application)
– SVC.h (user-side syscall stubs)
– Makefile (alternate build demo)

##### README for Architecture Clues
- Heavily relies on the Pico SDK (hardware abstraction layer for GPIO, UART, flash).
- Plans to replace the Pico SDK with a custom cross-compiler toolchain in the future.
- External littlefs integration provides block-device-backed storage.

##### Main Components
a. Hardware Layer
– RP2040 dual-core MCU, on-chip flash and RAM, peripherals (GPIO/UART/Timer).
b. Board Support Package (Pico SDK)
– Low-level drivers and runtime, imported via pico_sdk_import.cmake.
c. Kernel Core
– Startup/Reset (reset handler in exceptions.S)
– Exception vectors and IRQ handling (exceptions.S/.h)
– Supervisor Call (SVC) interface (SVC.h, ksvc.h)
– Task Management & Scheduling (proc.h, scheduler.h)
– IPC: queues and signals (queues.h)
– System call dispatcher (ksvc.c / OS.c)
d. Filesystem Service
– littlefs module under external/littlefs
– FS API wrappers in fs.h
e. User Application Layer
– ProjectTemplate/main.c (initial user code linked via linkerscript.ld)
f. Build System
– CMakeLists.txt driving compilation & linking
– ProjectTemplate/Makefile (alternative demo)
– Linker script for memory layout (linkerscript.ld)

##### Relationships & Data Flows
- On power-up, the reset vector (exceptions.S) initializes hardware via Pico SDK, then jumps to OS init (OS.c).
- Kernel initializes scheduler and queue structures.
- ProjectTemplate user task calls library functions → SVC triggers a trap → SVC handler dispatches into kernel syscall.
- Scheduler selects next runnable task, context switch via exceptions.S assembly stubs.
- File read/write calls in user code → FS API → littlefs functions → block reads/writes via Pico SDK flash driver.
- Build system invokes CMake → compiles C, assembly and links with linkerscript.ld into a .uf2 image for flashing.

##### Architectural Patterns & Principles
- Monolithic kernel with clear separation between user tasks and privileged services via SVC.
- Event-driven interrupt handling (exceptions/IRQ).
- Cooperative/preemptive scheduling (as implemented in scheduler.c).
- Modular external component (littlefs) integrated under external/ for filesystem support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Hardware["RP2040 MCU & Peripherals"]:::hardware
    end

    %% Board Support Package
    subgraph "Board Support Package (Pico SDK)"
        direction TB
        BSP["Pico SDK"]:::hardware
    end

    %% Kernel Core
    subgraph "Kernel Core"
        direction TB
        Startup["Startup / Reset Handler\n(exceptions.S)"]:::kernel
        Exceptions["Exception Vectors & IRQ Handling\n(exceptions.S, exceptions.h)"]:::kernel
        SVC_Kernel["Supervisor Call Interface\n(ksvc.h)"]:::kernel
        Syscall["System Call Dispatcher & Kernel Init\n(OS.c)"]:::kernel
        TaskMgmt["Task Management\n(proc.h)"]:::kernel
        Scheduling["Scheduling\n(scheduler.h)"]:::kernel
        Queues["IPC Queues\n(queues.h)"]:::kernel
        Defs["Definitions\n(defs.h)"]:::kernel
        Elf["ELF Utilities\n(elf.h)"]:::kernel
    end

    %% Filesystem Service
    subgraph "Filesystem Service"
        direction TB
        FS_API["FS API Wrappers\n(fs.h)"]:::external
        LittleFS["littlefs Library\n(external/littlefs)"]:::external
    end

    %% User Application Layer
    subgraph "User Application Layer"
        direction TB
        Main["User App\n(main.c)"]:::userapp
        SVC_User["User Syscall Stubs\n(SVC.h)"]:::userapp
        LinkerScript["Linker Script\n(linkerscript.ld)"]:::userapp
        Makefile["Alternative Build Demo\n(Makefile)"]:::userapp
    end

    %% Build System
    subgraph "Build System"
        direction TB
        CMake["CMakeLists.txt"]:::build
        Gitmodules[".gitmodules"]:::build
    end

    %% Initialization Flow
    Hardware -->|power-up| BSP
    BSP -->|reset vector| Startup
    Startup --> Exceptions
    Exceptions --> Syscall
    Syscall --> TaskMgmt
    TaskMgmt --> Scheduling
    Scheduling --> Queues

    %% Syscall Flow
    Main -->|library call| SVC_User
    SVC_User -->|SVC trap| SVC_Kernel
    SVC_Kernel -->|dispatch| Syscall

    %% Filesystem Flow
    Main -->|file I/O| FS_API
    FS_API --> LittleFS
    LittleFS -->|block driver| BSP

    %% Build Flow
    CMake -->|compiles| Hardware
    CMake -->|compiles| BSP
    CMake -->|links with| LinkerScript
    Gitmodules --> LittleFS
    Makefile -->|demo build| Main

    %% Click Events
    click Hardware "https://github.com/hamdannawaz582/picos/blob/main/pico_sdk_import.cmake"
    click BSP "https://github.com/hamdannawaz582/picos/blob/main/pico_sdk_import.cmake"
    click Startup "https://github.com/hamdannawaz582/picos/blob/main/exceptions.S"
    click Exceptions "https://github.com/hamdannawaz582/picos/blob/main/exceptions.S"
    click SVC_Kernel "https://github.com/hamdannawaz582/picos/blob/main/ksvc.h"
    click Syscall "https://github.com/hamdannawaz582/picos/blob/main/OS.c"
    click TaskMgmt "https://github.com/hamdannawaz582/picos/blob/main/proc.h"
    click Scheduling "https://github.com/hamdannawaz582/picos/blob/main/scheduler.h"
    click Queues "https://github.com/hamdannawaz582/picos/blob/main/queues.h"
    click Defs "https://github.com/hamdannawaz582/picos/blob/main/defs.h"
    click Elf "https://github.com/hamdannawaz582/picos/blob/main/elf.h"
    click FS_API "https://github.com/hamdannawaz582/picos/blob/main/fs.h"
    click LittleFS "https://github.com/hamdannawaz582/picos/tree/main/external/littlefs"
    click Main "https://github.com/hamdannawaz582/picos/blob/main/ProjectTemplate/main.c"
    click SVC_User "https://github.com/hamdannawaz582/picos/blob/main/ProjectTemplate/SVC.h"
    click LinkerScript "https://github.com/hamdannawaz582/picos/blob/main/ProjectTemplate/linkerscript.ld"
    click Makefile "https://github.com/hamdannawaz582/picos/tree/main/ProjectTemplate/Makefile"
    click CMake "https://github.com/hamdannawaz582/picos/blob/main/CMakeLists.txt"
    click Gitmodules "https://github.com/hamdannawaz582/picos/blob/main/.gitmodules"

    %% Styles
    classDef hardware fill:#add8e6,stroke:#000,stroke-width:1px
    classDef kernel fill:#98fb98,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef userapp fill:#ffff99,stroke:#000,stroke-width:1px
    classDef build fill:#d3d3d3,stroke:#000,stroke-width:1px
```
