# nornrtos/norncore architecture

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

- Interactive diagram: https://gitdiagram.com/nornrtos/norncore
- Repository: https://github.com/nornrtos/norncore

## Overview

nornOS is a small preemptive real-time kernel for AVR and ESP32, with a Linux host port. Its principal product workflow is an application initializing the kernel, registering tasks, then starting the scheduler; tasks use kernel services and portable HAL drivers to interact with hardware. The graph also preserves documented synchronization, timing, memory, watchdog, AMP, and flash capabilities. Unsampled module relationships are included only where the README describes them; source excerpts provide the application-specific links shown.

Main entry points: [`kernel/rtos.h`](https://github.com/nornrtos/norncore/blob/main/kernel/rtos.h) (Public RTOS API), [`applications/bTool/bTool.c`](https://github.com/nornrtos/norncore/blob/main/applications/bTool/bTool.c) (bTool Controller), [`kernel/rtos_kernel.c`](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_kernel.c) (Scheduler Core), [`applications/tc07/tc07_amp.c`](https://github.com/nornrtos/norncore/blob/main/applications/tc07/tc07_amp.c) (AMP Example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_btool["bTool Controller<br/>[bTool.c]"]
  node_tc_suite["Kernel Test Cases"]
  node_tc_amp["AMP Example<br/>[tc07_amp.c]"]
  node_tc_bench["Kernel Benchmark<br/>[tc10_bench.c]"]
  node_tc_depth["Stack Depth Test<br/>[tc12_depth.c]"]
end

subgraph group_kernel["Kernel"]
  node_api["Public RTOS API<br/>[rtos.h]"]
  node_scheduler["Scheduler Core<br/>[rtos_kernel.c]"]
  node_sync["Semaphores &amp; Mutexes<br/>[rtos_sync.c]"]
  node_queues["Queues &amp; Mailboxes<br/>[rtos_queue.c]"]
  node_notify["Task Notifications<br/>[rtos_notify.c]"]
  node_timers["Software Timers<br/>[rtos_timer.c]"]
  node_events["Event Groups<br/>[rtos_evgroup.c]"]
  node_memory["Heap &amp; Pools<br/>[rtos_heap.c]"]
  node_panic["Panic &amp; Watchdog<br/>[rtos_panic.c]"]
end

subgraph group_ports["CPU Ports"]
  node_avr_port["AVR Port<br/>[port_avr.c]"]
  node_xtensa_port["ESP32 Port<br/>[port_esp32.c]"]
  node_host_port["Host Port<br/>[port_host.c]"]
end

subgraph group_hal["Hardware Abstraction"]
  node_amp_link["AMP Link<br/>[amp.c]"]
  node_hal_uart["UART Driver<br/>[uart.h]"]
  node_hal_dht["DHT11 Driver<br/>[dht11.c]"]
  node_hal_lcd["LCD Driver<br/>[hd44780.c]"]
  node_hal_flash[("Flash Storage<br/>[flash.h]")]
  node_hal_board["Board &amp; GPIO<br/>[board.h]"]
end

node_app_user(("Application"))

node_app_user -->|"starts"| node_btool
node_app_user -->|"runs"| node_tc_suite
node_btool -->|"initializes tasks"| node_api
node_btool -->|"reads sensor"| node_hal_dht
node_btool -->|"updates display"| node_hal_lcd
node_btool -->|"uses console"| node_hal_uart
node_btool -->|"locks state"| node_sync
node_btool -->|"posts readings"| node_queues
node_tc_suite -->|"tests services"| node_api
node_tc_amp -->|"creates tasks"| node_api
node_tc_amp -->|"sends messages"| node_amp_link
node_tc_bench -->|"measures calls"| node_api
node_tc_depth -->|"tests stacks"| node_api
node_api -->|"schedules tasks"| node_scheduler
node_api -->|"offers synchronization"| node_sync
node_api -->|"offers queues"| node_queues
node_api -->|"offers notifications"| node_notify
node_api -->|"offers timers"| node_timers
node_api -->|"offers events"| node_events
node_api -->|"offers allocation"| node_memory
node_api -->|"offers recovery"| node_panic
node_scheduler -->|"uses CPU port"| node_avr_port
node_scheduler -->|"uses CPU port"| node_xtensa_port
node_scheduler -->|"uses CPU port"| node_host_port
node_amp_link -->|"wakes core"| node_xtensa_port
node_btool -->|"maps pins"| node_hal_board
node_api -.->|"persists app data"| node_hal_flash

click node_btool "https://github.com/nornrtos/norncore/blob/main/applications/bTool/bTool.c"
click node_tc_suite "https://github.com/nornrtos/norncore/tree/main/applications"
click node_tc_amp "https://github.com/nornrtos/norncore/blob/main/applications/tc07/tc07_amp.c"
click node_tc_bench "https://github.com/nornrtos/norncore/blob/main/applications/tc10/tc10_bench.c"
click node_tc_depth "https://github.com/nornrtos/norncore/blob/main/applications/tc12/tc12_depth.c"
click node_api "https://github.com/nornrtos/norncore/blob/main/kernel/rtos.h"
click node_scheduler "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_kernel.c"
click node_sync "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_sync.c"
click node_queues "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_queue.c"
click node_notify "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_notify.c"
click node_timers "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_timer.c"
click node_events "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_evgroup.c"
click node_memory "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_heap.c"
click node_panic "https://github.com/nornrtos/norncore/blob/main/kernel/rtos_panic.c"
click node_avr_port "https://github.com/nornrtos/norncore/blob/main/port/avr/port_avr.c"
click node_xtensa_port "https://github.com/nornrtos/norncore/blob/main/port/xtensa/port_esp32.c"
click node_host_port "https://github.com/nornrtos/norncore/blob/main/port/host/port_host.c"
click node_amp_link "https://github.com/nornrtos/norncore/blob/main/hal/xtensa/amp.c"
click node_hal_uart "https://github.com/nornrtos/norncore/blob/main/hal/uart.h"
click node_hal_dht "https://github.com/nornrtos/norncore/blob/main/hal/dht11.c"
click node_hal_lcd "https://github.com/nornrtos/norncore/blob/main/hal/hd44780.c"
click node_hal_flash "https://github.com/nornrtos/norncore/blob/main/hal/flash.h"
click node_hal_board "https://github.com/nornrtos/norncore/blob/main/hal/avr/board.h"

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_btool,node_tc_suite,node_tc_amp,node_tc_bench,node_tc_depth toneBlue
class node_api,node_scheduler,node_sync,node_queues,node_notify,node_timers,node_events,node_memory,node_panic toneAmber
class node_avr_port,node_xtensa_port,node_host_port toneMint
class node_amp_link,node_hal_uart,node_hal_dht,node_hal_lcd,node_hal_flash,node_hal_board toneRose
class node_app_user toneIndigo
```

## Components

### Applications

- [bTool Controller](https://github.com/nornrtos/norncore/blob/main/applications/bTool/bTool.c): `applications/bTool/bTool.c`
- [Kernel Test Cases](https://github.com/nornrtos/norncore/tree/main/applications): `applications`
- [AMP Example](https://github.com/nornrtos/norncore/blob/main/applications/tc07/tc07_amp.c): `applications/tc07/tc07_amp.c`
- [Kernel Benchmark](https://github.com/nornrtos/norncore/blob/main/applications/tc10/tc10_bench.c): `applications/tc10/tc10_bench.c`
- [Stack Depth Test](https://github.com/nornrtos/norncore/blob/main/applications/tc12/tc12_depth.c): `applications/tc12/tc12_depth.c`

### Kernel

- [Public RTOS API](https://github.com/nornrtos/norncore/blob/main/kernel/rtos.h): `kernel/rtos.h`
- [Scheduler Core](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_kernel.c): `kernel/rtos_kernel.c`
- [Semaphores & Mutexes](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_sync.c): `kernel/rtos_sync.c`
- [Queues & Mailboxes](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_queue.c): `kernel/rtos_queue.c`
- [Task Notifications](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_notify.c): `kernel/rtos_notify.c`
- [Software Timers](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_timer.c): `kernel/rtos_timer.c`
- [Event Groups](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_evgroup.c): `kernel/rtos_evgroup.c`
- [Heap & Pools](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_heap.c): `kernel/rtos_heap.c`
- [Panic & Watchdog](https://github.com/nornrtos/norncore/blob/main/kernel/rtos_panic.c): `kernel/rtos_panic.c`

### CPU Ports

- [AVR Port](https://github.com/nornrtos/norncore/blob/main/port/avr/port_avr.c): `port/avr/port_avr.c`
- [ESP32 Port](https://github.com/nornrtos/norncore/blob/main/port/xtensa/port_esp32.c): `port/xtensa/port_esp32.c`
- [Host Port](https://github.com/nornrtos/norncore/blob/main/port/host/port_host.c): `port/host/port_host.c`

### Hardware Abstraction

- [AMP Link](https://github.com/nornrtos/norncore/blob/main/hal/xtensa/amp.c): `hal/xtensa/amp.c`
- [UART Driver](https://github.com/nornrtos/norncore/blob/main/hal/uart.h): `hal/uart.h`
- [DHT11 Driver](https://github.com/nornrtos/norncore/blob/main/hal/dht11.c): `hal/dht11.c`
- [LCD Driver](https://github.com/nornrtos/norncore/blob/main/hal/hd44780.c): `hal/hd44780.c`
- [Flash Storage](https://github.com/nornrtos/norncore/blob/main/hal/flash.h): `hal/flash.h`
- [Board & GPIO](https://github.com/nornrtos/norncore/blob/main/hal/avr/board.h): `hal/avr/board.h`

### Other components

- **Application**

## Connections

- Application → bTool Controller: starts
- Application → Kernel Test Cases: runs
- bTool Controller → Public RTOS API: initializes tasks (evidence: `applications/bTool/bTool.c`)
- bTool Controller → DHT11 Driver: reads sensor (evidence: `applications/bTool/bTool.c`)
- bTool Controller → LCD Driver: updates display (evidence: `applications/bTool/bTool.c`)
- bTool Controller → UART Driver: uses console (evidence: `applications/bTool/bTool.c`)
- bTool Controller → Semaphores & Mutexes: locks state (evidence: `applications/bTool/bTool.c`)
- bTool Controller → Queues & Mailboxes: posts readings (evidence: `applications/bTool/bTool.c`)
- Kernel Test Cases → Public RTOS API: tests services (evidence: `applications/tc01/tc01_basics.c`)
- AMP Example → Public RTOS API: creates tasks (evidence: `applications/tc07/tc07_amp.c`)
- AMP Example → AMP Link: sends messages (evidence: `applications/tc07/tc07_amp.c`)
- Kernel Benchmark → Public RTOS API: measures calls (evidence: `applications/tc10/tc10_bench.c`)
- Stack Depth Test → Public RTOS API: tests stacks (evidence: `applications/tc12/tc12_depth.c`)
- Public RTOS API → Scheduler Core: schedules tasks (evidence: `kernel/rtos_kernel.c`)
- Public RTOS API → Semaphores & Mutexes: offers synchronization
- Public RTOS API → Queues & Mailboxes: offers queues
- Public RTOS API → Task Notifications: offers notifications
- Public RTOS API → Software Timers: offers timers
- Public RTOS API → Event Groups: offers events
- Public RTOS API → Heap & Pools: offers allocation
- Public RTOS API → Panic & Watchdog: offers recovery
- Scheduler Core → AVR Port: uses CPU port
- Scheduler Core → ESP32 Port: uses CPU port
- Scheduler Core → Host Port: uses CPU port
- AMP Link → ESP32 Port: wakes core
- bTool Controller → Board & GPIO: maps pins (evidence: `applications/bTool/bTool.c`)
- Public RTOS API → Flash Storage: persists app data