🫀 HeaRTOS

HeaRTOS — the heartbeat of small embedded systems.
A tiny, portable, modular real-time operating system written in C, with optional C++17 wrappers.
Minimal footprint, predictable behavior, and zero hardware dependencies in its core.

Version: 0.2.0

---

✨ Features

• Pure C core — no dynamic allocation, no HAL dependencies.
• Portable ports — currently: null, posix.
• Scheduler — priority, round-robin, or hybrid; RR currently rotates on yield/sleep.
• Binary semaphores — blocking take, try_take, ISR-safe give with FIFO wake-up.
• Static tasks — stacks and TCBS supplied by the application.
• CMake package — install and consume via find_package(HeaRTOS).
• Generated metadata — version and port headers at build time.
• Optional C++17 wrapper — header-only interface target when enabled.

The POSIX port is for logic verification, not timing accuracy. ucontext is used and supported on Linux/glibc.

---

📁 Repository Layout

heartos/
├── inc/                    # Public headers
├── src/                    # Core + port implementations
│   ├── core/               # Kernel internals
│   └── port/               # Architecture-specific backends (null, posix)
├── cpp/                    # Optional C++17 interface
├── examples/               # Example applications
├── tests/                  # POSIX test harness
├── docs/                   # Documentation
├── LICENSE
└── README.md

---

⚙️ Build

mkdir -p build && cd build
cmake -DHEARTOS_PORT=posix -DHEARTOS_BUILD_EXAMPLES=ON ..
cmake --build . -j$(nproc)
./examples/two_tasks/two_tasks

Install package:

cmake --install . --prefix "$PWD/install"

Consume from another CMake project:

find_package(HeaRTOS 0.2.0 REQUIRED)
add_executable(app main.c)
target_link_libraries(app PRIVATE HeaRTOS::heartos)

---

🧠 Concepts

Tick vs Timeslice

• Tick: base time unit generated by a timer interrupt (or POSIX signal). HeaRTOS increments a counter each tick and wakes sleepers.
• Timeslice: number of ticks a task may run before being rotated under RR. In v0.2.0, rotation happens on yield/sleep; strict preemption at slice end is planned.

Semaphores (binary)

• hrt_sem_init, hrt_sem_take, hrt_sem_try_take, hrt_sem_give, hrt_sem_give_from_isr.
• Use as a mutex substitute or an event signal. For mutex-like use, enabling immediate handoff on give is recommended (see roadmap).

---

🧩 CMake Options

Option	Default	Description
HEARTOS_ENABLE_CPP	OFF	Build C++ wrappers (header-only interface target)
HEARTOS_BUILD_EXAMPLES	ON	Build examples
HEARTOS_BUILD_TESTS	ON	Build test suite (POSIX port)

---

🗺️ Diagrams

Architecture

+-----------------------------------------------------------+
|                    Application Layer                      |
|  (User tasks: camera, UART downlink, HK/FDIR, etc.)       |
+---------------------------+-------------------------------+
|          HeaRTOS Core     |          HeaRTOS Port         |
|  - Scheduler              |  - hrt_port_start_systick()   |
|  - Tick management        |  - hrt_port_enter_scheduler() |
|  - Ready queues           |  - hrt_port_yield_to_scheduler() |
|  - Semaphores (binary)    |  - hrt_port_idle_wait()       |
+---------------------------+-------------------------------+
|                     Hardware / OS Primitives              |
| (Cortex-M SysTick/PendSV, or POSIX setitimer/ucontext)    |
+-----------------------------------------------------------+

Task State Machine

     +---------+
     | CREATED |
     +----+----+
          |
          v
     +----+----+
     |  READY  |<-----------------------------+
     +----+----+                              |
          |                                   |
          v                                   |
       +--+--+                                |
       | RUN | -- hrt_yield() --------------> |
       +--+--+                                |
          |                                   |
  hrt_sleep(ms)                               |
          v                                   |
       +--+----+       tick wakeup            |
       | SLEEP | -----------------------------+
       +-------+

  (If task function returns -> EXIT, not re-queued)

Scheduling Flow

Tick (ISR/signal) -> hrt__tick_isr():
  - g_tick++
  - wake any SLEEP tasks whose wake_tick <= now
  - hrt__pend_context_switch()  (set resched flag)

Scheduler loop (port):
  if resched flag:
     next = hrt__pick_next_ready()
     swapcontext/PendSV to next task

Task-level yield/sleep:
  - mark state (READY->queue or SLEEP)
  - hrt__pend_context_switch()
  - hrt_port_yield_to_scheduler()  (safe handoff from task ctx)

---

📜 License

Apache License 2.0 — see LICENSE.