# pok-kernel/pok architecture

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

- Interactive diagram: https://gitdiagram.com/pok-kernel/pok
- Repository: https://github.com/pok-kernel/pok

## Overview

##### Project type and purpose
- This is POK, a secure, safety-critical microkernel for embedded systems (ARINC653-compliant RTOS).
- It provides core kernel services (threads, time, partitions, synchronization), middleware APIs (ports, queues, sampling, blackboards), hardware drivers (network, console), and user-level libraries (libpok, libm, libc).

##### High-level architecture components
a. Kernel core
- Subsystems: bootloader, scheduler (time-partitioned & priority), thread manager, inter-partition communication, memory manager, error handling
b. Architecture abstraction layer
- Per-CPU implementations (x86, PPC, SPARC) under kernel/arch
- CPU context switch, interrupts, timers, syscalls
c. Device drivers
- Network card (rtl8029), console, other BSP code
d. Middleware services (within kernel/middleware)
- Ports: virtual, sampling, queueing, blackboards
- Resource management
e. User-level support libraries (libpok)
- Core API wrappers, ARINC653 bindings, C runtime (libc, libm)
f. User applications & examples
- Partition code in examples/, ARINC653 models in AADL
g. Build & test infrastructure
- Makefiles, ldscripts, test suite under testsuite/, CI pipelines

##### Component relationships & interactions
- User application (partition) → libpok API → software interrupt/syscall → kernel core
- Kernel core ↔ architecture layer (trap, context switch) ↔ hardware
- Kernel core ↔ device drivers ↔ hardware peripherals
- Kernel core ↔ middleware components (in-kernel) providing communication primitives
- Build/test tools orchestrate cross-compilation and QEMU/emulation

##### Key architectural patterns & principles
- Microkernel separation: minimal in-kernel code; services run in isolated partitions or libraries
- ARINC653 time-partitioning: fixed major cycles, partition slots
- Pluggable architecture support: each arch in its own directory with a common syscall interface
- Layered design: hardware abstraction → kernel core → middleware → user libs → applications

##### Technologies & frameworks
- C language, assembly for low-level arch code
- Makefile-driven build, ldscripts for linking kernel & partitions
- AADL models for ARINC653 configuration (examples/*.aadl)
- QEMU targets (x86-qemu, ppc prep, sparc leon3) for testing
- Continuous integration: Travis CI, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware"
        direction TB
        HW["Hardware Peripherals"]:::hardware
    end

    %% Architecture Abstraction Layer
    subgraph "Architecture Abstraction Layer" 
        direction TB
        ArchX86["kernel/arch/x86"]:::arch
        ArchPPC["kernel/arch/ppc"]:::arch
        ArchSPARC["kernel/arch/sparc"]:::arch
    end

    %% Kernel Core
    subgraph "Kernel Core" 
        direction TB
        Core["kernel/core"]:::kernel
        LibC_Kernel["kernel/libc"]:::kernel
    end

    %% Device Drivers (in-kernel)
    subgraph "Device Drivers" 
        direction TB
        DriverRTL["rtl8029.c"]:::driver
    end

    %% Middleware Services (in-kernel)
    subgraph "Middleware Services" 
        direction TB
        MiddlewareKernel["kernel/middleware"]:::middleware
    end

    %% User-Level Support Libraries
    subgraph "User-Level Libraries" 
        direction TB
        LibPOKCore["libpok/core"]:::userlib
        LibPOKArch["libpok/arch"]:::userlib
        LibPOKDriver["libpok/drivers/rtl8029.c"]:::userlib
        LibPOKMiddleware["libpok/middleware"]:::userlib
        LibC_User["libpok/libc"]:::userlib
        LibM_User["libpok/libm"]:::userlib
        LibPOKAda["libpok/ada/arinc653"]:::userlib
    end

    %% User Applications & Examples
    subgraph "User Applications & Examples" 
        direction TB
        Examples["examples"]:::app
    end

    %% Build & Test Infrastructure
    subgraph "Build & Test Infrastructure" 
        direction TB
        MakeRoot["Makefile (root)"]:::infra
        MakeKernel["kernel/Makefile"]:::infra
        LDScripts["misc/ldscripts"]:::infra
        TestSuite["testsuite"]:::infra
        QEMU["QEMU/Emulator"]:::infra
    end

    %% Interactions
    HW -->|Interrupts| ArchX86
    HW -->|Interrupts| ArchPPC
    HW -->|Interrupts| ArchSPARC

    ArchX86 -->|Context Switch/Trap| Core
    ArchPPC -->|Context Switch/Trap| Core
    ArchSPARC -->|Context Switch/Trap| Core

    Core -->|I/O Requests| DriverRTL
    DriverRTL -->|Access| HW

    Core -->|Provides| MiddlewareKernel
    MiddlewareKernel -->|Primitives| Core

    Examples -->|ARINC653 APIs| LibPOKCore
    Examples -->|Bind Ada| LibPOKAda

    LibPOKCore -->|Syscall API| Core
    LibPOKArch -->|Syscall Stubs| ArchX86
    LibPOKDriver -->|Driver Binding| DriverRTL
    LibPOKMiddleware -->|User APIs| MiddlewareKernel
    LibC_User -->|C Runtime| Examples
    LibM_User -->|Math API| Examples

    MakeRoot -->|Invokes| MakeKernel
    MakeKernel -->|Build| Core
    MakeKernel -->|Link| LDScripts
    MakeKernel -->|Compile Examples| Examples

    TestSuite -->|Runs on| QEMU
    QEMU -->|Emulates| HW
    QEMU -->|Loads| Core

    %% Click Events
    click Core "https://github.com/pok-kernel/pok/tree/main/kernel/core"
    click LibC_Kernel "https://github.com/pok-kernel/pok/tree/main/kernel/libc"
    click ArchX86 "https://github.com/pok-kernel/pok/tree/main/kernel/arch/x86"
    click ArchPPC "https://github.com/pok-kernel/pok/tree/main/kernel/arch/ppc"
    click ArchSPARC "https://github.com/pok-kernel/pok/tree/main/kernel/arch/sparc"
    click DriverRTL "https://github.com/pok-kernel/pok/blob/main/kernel/drivers/rtl8029.c"
    click MiddlewareKernel "https://github.com/pok-kernel/pok/tree/main/kernel/middleware"
    click LibPOKCore "https://github.com/pok-kernel/pok/tree/main/libpok/core"
    click LibPOKArch "https://github.com/pok-kernel/pok/tree/main/libpok/arch"
    click LibPOKDriver "https://github.com/pok-kernel/pok/blob/main/libpok/drivers/rtl8029.c"
    click LibPOKMiddleware "https://github.com/pok-kernel/pok/tree/main/libpok/middleware"
    click LibC_User "https://github.com/pok-kernel/pok/tree/main/libpok/libc"
    click LibM_User "https://github.com/pok-kernel/pok/tree/main/libpok/libm"
    click LibPOKAda "https://github.com/pok-kernel/pok/tree/main/libpok/ada/arinc653"
    click Examples "https://github.com/pok-kernel/pok/tree/main/examples"
    click LDScripts "https://github.com/pok-kernel/pok/tree/main/misc/ldscripts"
    click MakeRoot "https://github.com/pok-kernel/pok/tree/main/Makefile"
    click MakeKernel "https://github.com/pok-kernel/pok/tree/main/kernel/Makefile"
    click TestSuite "https://github.com/pok-kernel/pok/tree/main/testsuite"

    %% Styles
    classDef hardware fill:#f0f0f0,stroke:#888,stroke-width:1px
    classDef arch fill:#ffe4b5,stroke:#cc8400,stroke-width:2px
    classDef kernel fill:#ffcccc,stroke:#cc0000,stroke-width:2px
    classDef driver fill:#fff2b2,stroke:#ccaa00,stroke-width:2px
    classDef middleware fill:#d0f0c0,stroke:#68b868,stroke-width:2px
    classDef userlib fill:#c0d0ff,stroke:#3366cc,stroke-width:2px
    classDef app fill:#e0e0e0,stroke:#666,stroke-width:2px
    classDef infra fill:#e8d0ff,stroke:#8a2be2,stroke-width:2px
```
