# ventzl/cmrx architecture

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

- Interactive diagram: https://gitdiagram.com/ventzl/cmrx
- Repository: https://github.com/ventzl/cmrx

## Overview

##### Project type & purpose
- CMRX is a microkernel-based real-time operating system for Cortex-M microcontrollers (and POSIX/testing environments).
- Its primary goals are minimal privileged-mode code, full memory isolation (via the MPU), POSIX-like APIs, and a CMake-driven build.

##### File structure
- Top-level:
- cmake/ & CMakeLists.txt – build system and multi-arch support
- /cmrx – public kernel APIs (application, IPC, RPC, syscalls, util)
- src/os – kernel implementation (core, context switching, scheduler, syscalls, MPU setup) and architecture ports (ARM/CMSIS, Linux/posix, testing)
- src/lib – user-level library stubs for threads, mutexes, timers, RPC, etc.
- src/extra – optional userspace services (IPI, queue server, systick provider)
- testsuite/ & testing/ – integration and unit tests
- Layered ARCH directories under both cmake/arch and src/os/arch: these provide hardware-abstraction for Cortex-M, POSIX, testing.

##### Extract README insights
- Microkernel: small privileged core (~13 kB Flash, ~2 kB RAM), compile-time config
- Process isolation: one library = one userspace process, enforced by MPU
- IPC & RPC services facilitate safe communication
- CMake automates memory region setup, linking, and integration with vendor SDKs (CMSIS headers)

a. Main components (layers)
– Hardware Layer: CPU core, MPU, NVIC, SysTick timer, device buses/peripherals
– Microkernel Core: context switcher, scheduler, syscall handler, MPU manager, interrupt handling
– Architecture Abstraction (Porting Layer): CMSIS/arch code for ARM, POSIX shim for Linux/testing
– Kernel Services:
- IPC (mutex, signal, notify, shared memory, threads, timers)
- RPC framework (interface, implementation, internal marshaling)
- System calls / runtime / tracing
– User-level Libraries (Userspace Processes):
- One library = one process; thread APIs, device drivers, queue_server, ipi, systick modules
– Build & Tooling: CMake build scripts, Doxygen docs, test suite, CI pipelines
b. Relationships & data-flow
– Kernel Core ↔ MPU hardware (to enforce memory isolation)
– Build system orchestrates compilation of include/cmrx, src/os, src/lib, src/extra into separate binaries or static libraries
c. Architectural patterns & principles
– Microkernel: minimal privileged footprint, everything else runs in userspace
– Layered architecture: hardware → porting layer → core → services → user libraries
– Compile-time configuration (static composition of processes, memory regions)
d. Key technologies & frameworks
– CMake (multi-arch, cross-compile, testing integration)
– CMSIS (Cortex-M hardware abstraction)
– Doxygen (documentation)
– C11/CMake-based unit tests and testsuite for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        CPU["CPU Core"]:::hardware
        MPU_HW["MPU"]:::hardware
        NVIC["NVIC & SysTick"]:::hardware
    end

    %% Porting Layer
    subgraph "Porting Layer"
        ARM_PORT["ARM/CMSIS Port"]:::porting
        POSIX_SHIM["POSIX/Linux Shim"]:::porting
        TEST_STUB["Testing Stub"]:::porting
    end

    %% Kernel Core
    subgraph "Kernel Core"
        KERNEL_IMPL["Microkernel Core Implementation"]:::kernel
        MPU_MGR["MPU Manager"]:::kernel
        ISR["Interrupt Dispatcher"]:::kernel
    end

    %% Kernel Services
    subgraph "Kernel Services"
        IPC["IPC Services"]:::services
        RPC["RPC Framework"]:::services
    end

    %% User-level Libraries
    subgraph "User-level Libraries"
        LIBS["User Libraries"]:::userspace
        EXTRA["Extra Userspace Services"]:::userspace
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        CMAKE["CMake Build System"]:::tool
        DOCS["Documentation & Doxygen"]:::tool
        TESTS["Test Suites & CI"]:::tool
    end

    %% Connections
    CPU --> ARM_PORT
    CPU --> POSIX_SHIM
    CPU --> TEST_STUB
    ARM_PORT --> KERNEL_IMPL
    POSIX_SHIM --> KERNEL_IMPL
    TEST_STUB --> KERNEL_IMPL

    MPU_HW --> MPU_MGR
    MPU_MGR --> MPU_HW

    NVIC --> ISR
    ISR --> KERNEL_IMPL

    KERNEL_IMPL --> IPC
    KERNEL_IMPL --> RPC

    LIBS -->|"syscalls"| KERNEL_IMPL
    KERNEL_IMPL -->|"syscall handler"| LIBS

    IPC <--> KERNEL_IMPL
    RPC <--> KERNEL_IMPL

    EXTRA --> LIBS

    CMAKE -->|"builds"| KERNEL_IMPL
    CMAKE -->|"builds"| LIBS
    CMAKE -->|"generates docs"| DOCS
    CMAKE -->|"runs tests"| TESTS

    %% Click Events
    click CMAKE "https://github.com/ventzl/cmrx/blob/master/CMakeLists.txt"
    click CMAKE "https://github.com/ventzl/cmrx/tree/master/cmake/"
    click KERNEL_IMPL "https://github.com/ventzl/cmrx/tree/master/src/os/kernel/"
    click ARM_PORT "https://github.com/ventzl/cmrx/tree/master/src/os/arch/arm/"
    click POSIX_SHIM "https://github.com/ventzl/cmrx/tree/master/src/os/arch/linux/posix/"
    click TEST_STUB "https://github.com/ventzl/cmrx/tree/master/src/os/arch/testing/"
    click MPU_MGR "https://github.com/ventzl/cmrx/blob/master/src/os/kernel/mpu.h"
    click ISR "https://github.com/ventzl/cmrx/blob/master/src/os/kernel/isr.c"
    click LIBS "https://github.com/ventzl/cmrx/tree/master/src/lib/"
    click EXTRA "https://github.com/ventzl/cmrx/tree/master/src/extra/"
    click DOCS "https://github.com/ventzl/cmrx/tree/master/Doxyfile"
    click DOCS "https://github.com/ventzl/cmrx/tree/master/man/"
    click TESTS "https://github.com/ventzl/cmrx/tree/master/testsuite/"
    click TESTS "https://github.com/ventzl/cmrx/tree/master/testing/"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#666,stroke-width:1px;
    classDef porting fill:#ffe0b3,stroke:#cc6600,stroke-width:1px;
    classDef kernel fill:#ff9999,stroke:#cc0000,stroke-width:1px;
    classDef services fill:#d9b3ff,stroke:#8000ff,stroke-width:1px;
    classDef userspace fill:#99ccff,stroke:#0066cc,stroke-width:1px;
    classDef tool fill:#ccffcc,stroke:#009900,stroke-width:1px;
```
