tin

Purpose

tin is a C++ framework for developing deterministic real-time C++ software for bare-metal, arm, and x86 architectures. It gives teams a small, bounded substrate for runtime infrastructure and explicit behavior modeling: queues, channels, tasks, timers, typed events, state machines, I/O facades, platform contracts, and adapter boundaries.

The generated API reference covers tin, tsm, tio, and thal headers. tin API lists the main entry points.

Why Use tin

Use tin when system behavior and runtime mechanics need to be explicit, bounded, portable, and reviewable:

• model product behavior with typed state machines;
• move data through fixed-capacity queues and channels with explicit overflow policy;
• drive time through integer ticks and bounded timer queues;
• adapt drivers, simulators, middleware, or replay inputs into local typed events;
• run the same behavior in host tests, embedded firmware, simulation shells, and target adapters;
• share deterministic runtime infrastructure across host tests, firmware, and target adapters.

Organization

Start with product_overview for positioning, architecture for package boundaries, and public_api_boundary for the supported API surface. Contributors should begin with developer_onboarding before changing architecture, tests, tools, platform adapters, or docs.

Contributor curriculum:

• framework walkthrough: one measured value moving from driver input to typed event, HSM transition, and output adapter.
• minimal complete tin app: a small host-buildable application shape using a channel, payload event, queued runtime, and caller-owned loop.
• design invariants: the properties contributors should preserve while changing tin.
• decision guide: where code belongs and which runtime shape to choose.
• testing map: which tests prove which contracts.
• glossary: tin-specific vocabulary.
• contributor recipes: scoped workflows for common change types.

Public surfaces:

• tin API: main headers and runtime entry points.
• channels: bounded typed storage and handle APIs.
• actors: local composition with ports, links, groups, retry behavior, and caller-owned execution.
• coroutines: first-class static task model for workflows around HSM runtimes, actors, channels, and platform adapters.
• runtime reference: lower-level task, timer, event-concept, dispatch-context, and policy details.
• actor tutorial: a complete local runtime composition example with source, controller, reporter, links, execution loop, and resource accounting.
• tsm: HSM definitions, definition/context structure, transition authoring, runtime policies, logging, and inspection.
• tio: GPIO, ADC, UART, SPI, I2C, CAN, PWM, and async driver facade concepts.
• thal: platform profiles, compiler contracts, and target adapter boundaries.
• Tooling: command line workflows for .hsm, JSON, diagrams, Python simulators, C++ scaffolds, and pybind11 scaffolds.