Revera

A small real-time kernel with hardware-enforced isolation.

by VIACERTO LLC

Revera is a portable real-time kernel for microcontrollers and embedded SoCs. Alongside the usual RTOS services — preemptive scheduling, mutexes, semaphores, condition variables, SMP and AMP — its distinguishing feature is a memory fence that the hardware enforces even against the kernel itself: threads, and whole scheduling islands, can be confined so that a fault or a compromise in one cannot reach another’s memory.

New here? Start with Getting started — from nothing to a running kernel in about ten minutes. The API reference documents the stable 0.1.0 surface, and the readiness dashboard is the honest, live per-feature / per-architecture status.

Getting Started

• Getting started with Revera
  • 1. What you need
  • 2. Run your first kernel (on your desktop)
  • 3. Run it under an emulator
  • 4. Run the tests
  • 5. Anatomy of the app
  • 6. Write your own app
  • 7. Tuning the build (profiles + knobs)
  • Where to go next
• Writing examples — naming & structure convention
  • One example, one feature
  • Directory naming
  • Structure & comment style
  • Porting legacy examples

Architecture

• The arch interface: common-denominator analysis
  • 1. The observed surface (interface element × port)
  • 2. The tiering that falls out
  • 3. The interface as built (tiered, defaulted)
  • 4. Findings — what’s proven and what’s still open
  • 5. The absorbed-axis ports (ADR 0001)
  • 6. Board-owned time and tick glue (arm family)
  • 7. msp430 and tricore: two different kinds of “header-only”
• Board ↔ kernel boundary contract
  • 0. The claim this document backs
  • 1. The three layers, and where the line sits
  • 2. Two directions across the line
  • 3. Prerequisites — what must hold before tk_kernel_start()
  • 4. Hooks — the Layer-2 seam (fixed and enumerable)
  • 5. Who provides Layer 1 — a / b / c
  • 6. Port a board — the 1-2-3
  • 7. Why it is a matrix, not a flat list
  • 8. Coverage matrix — the four root boards
  • 9. Per-arch appendices
• Composability — the building-block contract
  • 1. Thesis
  • 2. The layer model and the one-way dependency rule
  • 3. The brick map (what the build actually sees)
  • 4. The stud catalog — the approved connectors
  • 5. The glue anti-patterns — forbidden
  • 6. Invariants and their enforcement
  • 7. Current state — an honest scorecard
  • 8. Worked example — nRF52 tick: glue → stud
  • 9. Open work (the path to “build without fear”)
• HAL architecture — the peripheral abstraction layer
  • 1. Goals and non-goals
  • 2. The layered architecture
  • 3. The three durable rules
  • 4. tk_board and tk_console — bring-up and text
  • 5. Settled decisions
  • 6. Module contracts (minimal root)
  • 7. The frozen public contract
  • 8. Status model — class vs detail
  • 9. The Option-C resolver seam
  • 10. Boot ordering
  • 11. Multi-core / SMP readiness
  • 12. Conventions
  • 13. Portability evidence
  • 14. Scope and roadmap (minimal root)
• Kernel header tiers — the public/internal API boundary
  • 1. The problem this closes
  • 2. The consumers (who includes what)
  • 3. The four-tier boundary (the decision)
  • 4. The manifest — every symbol, placed
  • 5. The orthogonal dimension: privilege (TK_CONFIG_UNPRIV_THREADS)
  • 6. Config-gated public surface (the one gate idiom)
  • 7. Ergonomics — kept, they are proven
  • 8. Residual leak (open)
• Portable security & safety API — the explicit-control model
  • 1. Principle
  • 2. Who owns the setup — a spectrum, the engineer chooses
  • 3. The vocabulary (first-class axes)
  • 4. The capability rule — loud vs collapse
  • 5. The kernel owns the hardware setup
  • 6. One image or two — the build-shape a world split forces
  • 7. Worked examples (the engineer’s scenarios)
  • 8. Portability matrix (illustrative)
  • 9. Where this stands — proven, and the linchpin
• The SMP model
  • The one tension to settle first: shared pool vs per-core lists
  • The settled SMP model (verified against kernel/tk_kernel.c)
  • F4 — the cooperative-switch reconcile
  • Two hard-won SMP details to carry forward (do not re-derive)
  • Affinity (proven — keep as first-class, config-gated)
  • Round-robin fairness across cores (phase-offset first slice)
  • The arch Tier-2 contract (from arch-interface.md)
  • Separate-kernel AMP: in scope (ADR 0002)
  • What this settles
• Synchronization: choosing and using a cross-core primitive
  • 1. The fork that decides everything: two regimes
  • 2. The mechanism menu
  • 3. tk_spinlock — universal mutual exclusion
  • 4. tk_seqlock — read-mostly consistency
  • 5. Placement across an AMP boundary
  • 6. Related
• Tick ownership & preemption-integration policy
  • The three actors (this is the whole model)
  • Policy resolutions
  • The board tick contract (what an integrator writes)
  • What this settles
• Timekeeping in k2 — timers, time sources, and the system clock
  • 1. The three kinds of “timer” in k2 — keep them distinct
  • 2. The kernel tick / system time — per board (audited, 4 real boards)
  • 3. tk_gpt — application countdown timers (not yet ported to root)
  • 4. Busy-wait delays (not yet ported to root)
  • 5. Public API surface today
  • 6. The architectural gap that motivated tk_time.h (history)
  • 7. tk_time_ms() / tk_time_us() — implemented
• Kernel-owned synchronization objects
  • 1. Two holes a struct-based, app-owned design would have
  • 2. The shape: kernel-owned pools + opaque integer handles
  • 3. The syscall boundary: the kernel resolves, never dereferences an app pointer
  • 4. What this closes, concretely
  • 5. Semantics unchanged by the ownership model
  • 6. TK_DET — currently a placeholder at root
  • 7. Related
• Kernel-RAM isolation (full-lockdown, part 1 of 2)
  • 1. Two knobs, not one — read this first
  • 2. What “full lockdown” protects and why it’s needed
  • 3. The blocker this mechanism forces: no unprivileged path may touch kernel state directly
  • 4. Worked example: ARMv7-M sub-region-disable (nRF52832 / PCA10040)
  • 5. The general contract (arch-neutral)
  • 6. Root status: what’s wired today vs. what a board still owes
  • 7. Multi-arch generalization
  • 8. Related
• Per-thread stack isolation (full-lockdown, part 2 of 2)
  • 1. The mechanism: a per-thread stack region, reprogrammed every switch
  • 2. Declaring an isolatable stack — TK_THREAD_STACK
  • 3. Worked example: ARMv7-M power-of-two stacks (nRF52832 / PCA10040)
  • 4. Region budget (ARMv7-M)
  • 5. The general contract, and multi-arch generalization
  • 6. Root status: the guard rail is wired (fail-closed at creation)
  • 7. Validation shape
  • 8. Related

API Reference

• Public API reference — 0.1.0 stable surface

Porting Guides

• Porting the tk kernel to a new CPU (arch/<cpu>)
  • 1. Capability macros (in kernel_arch.h)
  • 1b. Optional tiers — SMP, MPU, unprivileged, context-reclaim
  • 2. Required types + functions
  • 3. The interrupt-state contract (get this right)
  • 4. Which preemption hook to call
  • 5. Stacks and the trap frame
  • 6. CPU-architecture vs board-specific
  • 7. New-port checklist
• Board bring-up — the minimal foundation
  • The principle: bring up THIN
  • The foundation ladder
  • Explicitly NOT the foundation (opt-in, on demand)
  • Bring-up discipline
  • Portability landmines — aim each new board at one
  • Reference boards to copy from

Design Decisions (ADRs)

• ADR 0001 — Foreign-architecture support policy (“draw the line by axis”)
• ADR 0002 — Multi-instance kernel: un-globaling the singleton, AMP islands in scope (“one model, N instances”)
• ADR 0003 — The supervisor-fence seam: a per-instance HW memory boundary that binds the kernel
• ADR 0004 — Per-island memory isolation: fencing kernel-owned RAM + a first-class isolation attribute
• ADR 0005 — System-side (TrustZone-AMP) fence for a secondary core that has no MPU of its own

Evaluation

• Evaluating Revera
  • The differentiator
  • Core kernel
  • Portability, configuration, ergonomics
  • Product & assurance
• Configuration Flexibility and Modularization
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Connectivity and Protocol Stacks
  • How Revera answers it — honestly
  • Available from the project’s history (roadmap / on request — not in 0.1.0)
  • Learn more
• Hardware Abstraction and Portability
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Available from the project’s history (roadmap / on request — not in 0.1.0)
  • Limits
  • Learn more
• Inter-Task Communication (ITC) and Synchronization
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Interrupt Handling and Synchronization
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Commercial and Licensing Lifecycle
  • How Revera answers it
  • At a glance
  • Limits (honest)
  • Learn more
• Memory Management and Footprint
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Memory Protection & Isolation
  • How Revera answers it
  • The ladder — what it enforces · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Multi-Core Architecture Support
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Safety, Security, and Compliance Certifications
  • How Revera answers it — honestly
  • Available from the project’s history (roadmap / on request — not in 0.1.0)
  • Learn more
• Scheduler and Task Management
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more
• Standardization and API Ergonomics
  • How Revera answers it
  • What maps · how to use it
  • The deliberate divergences (kept as-is, documented)
  • What can be claimed (honest)
  • Learn more
• Ecosystem, Tooling, and Observability
  • How Revera answers it
  • Feature · how to turn it on · how to use it · where it works
  • Limits & roadmap
  • Learn more

Project & Status

• 0.1.0 Readiness Dashboard — LIVE
• Return-to-root roadmap — landing the reshaped kernel as THE kernel
• tk — Safety & Security Features (cross-arch reference, staged index)
• Revera 0.1.0 — release manifest
• Announcing Revera 0.1.0