# h-000-h/mini-os architecture

> Architecture diagram of the GitHub repository h-000-h/mini-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h-000-h/mini-os
- Repository: https://github.com/h-000-h/mini-os

## Overview

mini-os is a freestanding, single-core RTOS kernel for microcontrollers. Its user-facing workflow is an application creating threads and kernel objects; the scheduler selects runnable threads, tick processing releases delays and timeouts, and the architecture port performs context switches. Synchronization, message queues, timers, and memory management are distinct supporting capabilities. README documents optional features and additional architecture ports whose detailed implementations were not sampled, so those links are limited to documented ownership.

Main entry points: [`src/thread.c`](https://github.com/h-000-h/mini-os/blob/main/src/thread.c) (Thread lifecycle), [`src/schedule.c`](https://github.com/h-000-h/mini-os/blob/main/src/schedule.c) (Priority scheduler), [`src/timer.c`](https://github.com/h-000-h/mini-os/blob/main/src/timer.c) (Timer service), [`src/semaphore.c`](https://github.com/h-000-h/mini-os/blob/main/src/semaphore.c) (Semaphores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Thread execution"]
  node_threads["Thread lifecycle<br/>[thread.c]"]
  node_scheduler["Priority scheduler<br/>[schedule.c]"]
end

subgraph group_sync["Synchronization and communication"]
  node_sem["Semaphores<br/>[semaphore.c]"]
  node_mutex["Mutexes<br/>[mutex.c]"]
  node_events["Event groups<br/>[event.c]"]
  node_queue["Message queues<br/>[queue.c]"]
end

subgraph group_time["Time services"]
  node_timers["Timer service<br/>[timer.c]"]
  node_tickwheel["Thread tick wheel<br/>[schedule.c]"]
  node_ticks["System tick<br/>[port.h]"]
end

subgraph group_memory["Memory management"]
  node_heap[("Heap allocator<br/>[memory.c]")]
end

subgraph group_platform["Architecture support"]
  node_port["Cortex-M port<br/>[port.c]"]
  node_portasm["Context switch<br/>[port.S]"]
  node_riscv["RISC-V port<br/>[port.c]"]
  node_armport["ARM port<br/>[port.c]"]
end

node_app(("Application"))

node_app -->|"creates threads"| node_threads
node_app -->|"uses"| node_sem
node_app -->|"locks"| node_mutex
node_app -.->|"waits on"| node_events
node_app -->|"sends and receives"| node_queue
node_app -->|"configures"| node_timers
node_threads -->|"allocates"| node_heap
node_threads -->|"makes runnable"| node_scheduler
node_scheduler -->|"requests switch"| node_portasm
node_portasm -->|"restores thread"| node_threads
node_port -->|"dispatches SVC"| node_portasm
node_riscv -.->|"provides port"| node_scheduler
node_mutex -->|"parks waiters"| node_sem
node_sem -->|"blocks and wakes"| node_threads
node_queue -->|"blocks and wakes"| node_threads
node_events -.->|"blocks and wakes"| node_threads
node_ticks -->|"advances tick"| node_scheduler
node_scheduler -->|"expires waits"| node_tickwheel
node_ticks -->|"advances wheel"| node_timers
node_timers -->|"wakes service thread"| node_sem
node_timers -->|"requests ISR switch"| node_scheduler
node_mutex -->|"recomputes priority"| node_scheduler
node_threads -->|"frees terminated threads"| node_heap

click node_threads "https://github.com/h-000-h/mini-os/blob/main/src/thread.c"
click node_scheduler "https://github.com/h-000-h/mini-os/blob/main/src/schedule.c"
click node_port "https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.c"
click node_portasm "https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.S"
click node_riscv "https://github.com/h-000-h/mini-os/blob/main/arch/risc-v/port.c"
click node_sem "https://github.com/h-000-h/mini-os/blob/main/src/semaphore.c"
click node_mutex "https://github.com/h-000-h/mini-os/blob/main/src/mutex.c"
click node_events "https://github.com/h-000-h/mini-os/blob/main/src/event.c"
click node_queue "https://github.com/h-000-h/mini-os/blob/main/src/queue.c"
click node_timers "https://github.com/h-000-h/mini-os/blob/main/src/timer.c"
click node_heap "https://github.com/h-000-h/mini-os/blob/main/src/memory.c"
click node_tickwheel "https://github.com/h-000-h/mini-os/blob/main/src/schedule.c"
click node_ticks "https://github.com/h-000-h/mini-os/blob/main/inc/port.h"
click node_armport "https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_threads,node_scheduler toneBlue
class node_sem,node_mutex,node_events,node_queue toneAmber
class node_timers,node_tickwheel,node_ticks toneMint
class node_heap toneRose
class node_port,node_portasm,node_riscv,node_armport,node_app toneIndigo
```

## Components

### Thread execution

- [Thread lifecycle](https://github.com/h-000-h/mini-os/blob/main/src/thread.c): `src/thread.c`
- [Priority scheduler](https://github.com/h-000-h/mini-os/blob/main/src/schedule.c): `src/schedule.c`

### Synchronization and communication

- [Semaphores](https://github.com/h-000-h/mini-os/blob/main/src/semaphore.c): `src/semaphore.c`
- [Mutexes](https://github.com/h-000-h/mini-os/blob/main/src/mutex.c): `src/mutex.c`
- [Event groups](https://github.com/h-000-h/mini-os/blob/main/src/event.c): `src/event.c`
- [Message queues](https://github.com/h-000-h/mini-os/blob/main/src/queue.c): `src/queue.c`

### Time services

- [Timer service](https://github.com/h-000-h/mini-os/blob/main/src/timer.c): `src/timer.c`
- [Thread tick wheel](https://github.com/h-000-h/mini-os/blob/main/src/schedule.c): `src/schedule.c`
- [System tick](https://github.com/h-000-h/mini-os/blob/main/inc/port.h): `inc/port.h`

### Memory management

- [Heap allocator](https://github.com/h-000-h/mini-os/blob/main/src/memory.c): `src/memory.c`

### Architecture support

- [Cortex-M port](https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.c): `arch/arm/cortex-m/port/port.c`
- [Context switch](https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.S): `arch/arm/cortex-m/port/port.S`
- [RISC-V port](https://github.com/h-000-h/mini-os/blob/main/arch/risc-v/port.c): `arch/risc-v/port.c`
- [ARM port](https://github.com/h-000-h/mini-os/blob/main/arch/arm/cortex-m/port/port.c): `arch/arm/cortex-m/port/port.c`

### Other components

- **Application**

## Connections

- Application → Thread lifecycle: creates threads
- Application → Semaphores: uses
- Application → Mutexes: locks
- Application → Event groups: waits on
- Application → Message queues: sends and receives
- Application → Timer service: configures
- Thread lifecycle → Heap allocator: allocates
- Thread lifecycle → Priority scheduler: makes runnable
- Priority scheduler → Context switch: requests switch
- Context switch → Thread lifecycle: restores thread
- Cortex-M port → Context switch: dispatches SVC
- RISC-V port → Priority scheduler: provides port
- Mutexes → Semaphores: parks waiters
- Semaphores → Thread lifecycle: blocks and wakes
- Message queues → Thread lifecycle: blocks and wakes
- Event groups → Thread lifecycle: blocks and wakes
- System tick → Priority scheduler: advances tick
- Priority scheduler → Thread tick wheel: expires waits
- System tick → Timer service: advances wheel
- Timer service → Semaphores: wakes service thread
- Timer service → Priority scheduler: requests ISR switch
- Mutexes → Priority scheduler: recomputes priority
- Thread lifecycle → Heap allocator: frees terminated threads