# pdlsurya/sanortos architecture

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

- Interactive diagram: https://gitdiagram.com/pdlsurya/sanortos
- Repository: https://github.com/pdlsurya/sanortos

## Overview

##### Project Type and Purpose
- This is an embedded Real-Time Operating System (RTOS) library (sanoRTOS) written in C, targeting ARM Cortex-M and RISC-V microcontrollers.
- It provides preemptive, priority-based scheduling, synchronization primitives (mutex, semaphore, condition variable), inter-task message queues, software timers, and SMP support.

##### File Structure Analysis
- Top-level directories:
- /sanoRTOS – public API headers (task management, synchronization, scheduler, timer)
- source/       – core kernel implementation (scheduler, task queue, synchronization primitives)
- ports/        – Hardware Abstraction Layer (HAL) for each supported architecture (ARM/nrf52, ARM/rp2350, ARM/stm32, RISC-V/esp32c6, RISC-V/rp2350)
- Build/deployment artifacts are minimal; no complex scripts. The design enforces a clear separation between the portable kernel core (source + include) and the architecture-specific port layer.

##### Key Components
a. Application Layer
- User tasks defined via TASK_DEFINE, calling API functions (taskStart, mutexLock, msgQueueSend, etc.).
b. API Layer (include/sanoRTOS headers)
- Task Management, Spin‐Lock, Mutex, Semaphore, Condition Variable, Message Queue, Timer APIs.
c. Kernel Core (source/*.c)
- scheduler.c: manages ready queues and context switches
- taskQueue.c: priority‐based task ready list
- synchronization primitives (mutex.c, semaphore.c, conditionVariable.c, messageQueue.c)
- timer.c: software timer management
- mem.c: stack overflow monitoring
d. HAL / Port Layer (ports/…/port.c, port.S)
- port_init: configure CPU registers for context switching
- osSysTick_Handler, PendSV_Handler, SVC_Handler: interrupt handlers for tick, context switch, system calls
- low-level routines to save/restore CPU context
e. Hardware Layer
- Microcontroller cores (ARM Cortex-M, RISC-V), SysTick timer, memory subsystem, NVIC (interrupt controller).

##### Relationships and Data Flows
- Application → API calls → Kernel Core
- Kernel Core invokes Port Layer functions for context save/restore and interrupt registration
- Port Layer interacts with Hardware (SysTick interrupt, CPU registers)
- Scheduler tick (hardware interrupt) triggers osSysTick_Handler → schedulerCore → PendSV to perform context switch
- Tasks synchronize via kernel primitives, communicate via message queues
- Software timers maintained in kernel core, driven by SysTick ticks

##### Architectural Patterns and Principles
- Layered architecture: Application → API → Kernel Core → HAL → Hardware
- Separation of concerns: Core RTOS logic is portable; ports handle architecture specifics
- Static object definitions (macros for TASK_DEFINE, MUTEX_DEFINE) for zero dynamic allocation
- Priority-based preemptive scheduling with optional priority inheritance
- Modular synchronization primitives for extensibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        App["Application Tasks"]:::application
    end

    %% RTOS API Layer
    subgraph "RTOS API"
        TaskAPI["Task Management API"]:::api
        SpinAPI["Spin-Lock API"]:::api
        MutexAPI["Mutex API"]:::api
        SemAPI["Semaphore API"]:::api
        CVAPI["Condition Variable API"]:::api
        MsgAPI["Message Queue API"]:::api
        TimerAPI["Software Timer API"]:::api
        MemAPI["Memory Monitoring API"]:::api
        SchedAPI["Scheduler API"]:::api
        TQAPI["Task Queue API"]:::api
    end

    %% RTOS Core Layer
    subgraph "RTOS Core"
        ScCore["Scheduler Core"]:::core
        TQCore["Task Queue Module"]:::core
        TaskCore["Task Core"]:::core
        MutexCore["Mutex Module"]:::core
        SemCore["Semaphore Module"]:::core
        CVCore["Condition Variable Module"]:::core
        MsgCore["Message Queue Module"]:::core
        TimerCore["Software Timer Module"]:::core
        MemCore["Memory Monitoring Module"]:::core
    end

    %% HAL / Port Layer
    subgraph "HAL / Port Layer"
        ARMnRF["ARM Cortex-M nRF52 Port"]:::hal
        ARMrP["ARM Cortex-M RP2350 Port"]:::hal
        ARMS["ARM Cortex-M STM32 Port"]:::hal
        RVESP["RISC-V ESP32C6 Port"]:::hal
        RVRP["RISC-V RP2350 Port"]:::hal
    end

    %% Hardware Layer
    subgraph "Hardware"
        CPU["CPU Cores"]:::hw
        SysTick["SysTick Timer"]:::hw
        NVIC["NVIC (Interrupt Controller)"]:::hw
        MemHW["Memory Subsystem"]:::hw
    end

    %% Connections: Application to API
    App -->|"uses"| TaskAPI
    App -->|"uses"| MutexAPI
    App -->|"uses"| MsgAPI

    %% API to Core
    TaskAPI -->|"calls"| TaskCore
    SchedAPI -->|"calls"| ScCore
    TQAPI -->|"calls"| TQCore
    MutexAPI -->|"calls"| MutexCore
    SemAPI -->|"calls"| SemCore
    CVAPI -->|"calls"| CVCore
    MsgAPI -->|"calls"| MsgCore
    TimerAPI -->|"calls"| TimerCore
    MemAPI -->|"calls"| MemCore

    %% Core to HAL
    ScCore -->|"invoke port_init"| ARMnRF
    ScCore -->|"invoke port_init"| ARMrP
    ScCore -->|"invoke port_init"| ARMS
    ScCore -->|"invoke port_init"| RVESP
    ScCore -->|"invoke port_init"| RVRP

    %% HAL to Hardware
    ARMnRF -->|"context save/restore"| CPU
    ARMnRF -->|"register ISR"| NVIC
    ARMrP -->|"context save/restore"| CPU
    ARMS -->|"context save/restore"| CPU
    RVESP -->|"context save/restore"| CPU
    RVRP -->|"context save/restore"| CPU

    %% Interrupt flow
    SysTick -.->|"tick interrupt"| ARMnRF
    NVIC -.->|"pendSV interrupt"| ARMnRF

    %% Styles
    classDef application fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#cfc,stroke:#333,stroke-width:1px
    classDef core fill:#ccf,stroke:#333,stroke-width:1px
    classDef hal fill:#ffc,stroke:#333,stroke-width:1px
    classDef hw fill:#eee,stroke:#333,stroke-width:1px

    %% Click Events: API
    click TaskAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/task.h"
    click SpinAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/spinLock.h"
    click MutexAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/mutex.h"
    click SemAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/semaphore.h"
    click CVAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/conditionVariable.h"
    click MsgAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/messageQueue.h"
    click TimerAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/timer.h"
    click MemAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/mem.h"
    click SchedAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/scheduler.h"
    click TQAPI "https://github.com/pdlsurya/sanortos/blob/main/include/sanoRTOS/taskQueue.h"

    %% Click Events: Core
    click ScCore "https://github.com/pdlsurya/sanortos/blob/main/source/scheduler.c"
    click TQCore "https://github.com/pdlsurya/sanortos/blob/main/source/taskQueue.c"
    click TaskCore "https://github.com/pdlsurya/sanortos/blob/main/source/task.c"
    click MutexCore "https://github.com/pdlsurya/sanortos/blob/main/source/mutex.c"
    click SemCore "https://github.com/pdlsurya/sanortos/blob/main/source/semaphore.c"
    click CVCore "https://github.com/pdlsurya/sanortos/blob/main/source/conditionVariable.c"
    click MsgCore "https://github.com/pdlsurya/sanortos/blob/main/source/messageQueue.c"
    click TimerCore "https://github.com/pdlsurya/sanortos/blob/main/source/timer.c"
    click MemCore "https://github.com/pdlsurya/sanortos/blob/main/source/mem.c"

    %% Click Events: HAL
    click ARMnRF "https://github.com/pdlsurya/sanortos/blob/main/ports/arm/nrf52/port.c"
    click ARMrP "https://github.com/pdlsurya/sanortos/blob/main/ports/arm/rp2350/port.c"
    click ARMS "https://github.com/pdlsurya/sanortos/blob/main/ports/arm/stm32/port.c"
    click RVESP "https://github.com/pdlsurya/sanortos/blob/main/ports/riscv/esp32c6/port.c"
    click RVRP "https://github.com/pdlsurya/sanortos/blob/main/ports/riscv/rp2350/port.c"
```
