thal

Purpose

thal is the platform and HAL boundary. It names target profiles, compiler assumptions, scheduler constraints, and adapter shapes that bind the same runtime model to host, bare-metal, RTOS, and realtime OS deployments.

Use thal for:

• target profile declarations;
• compile-time checks for exception and RTTI policy;
• platform boundary documentation;
• adapter code that converts target wakeups, ticks, interrupts, or OS events into tin runtime work.

API Entry Points

• tin/platform.h for tin::platform.
• thal.h for the thal shorthand namespace alias.
• tin::platform::host_linux_profile, tin::platform::bare_metal_arm_profile, tin::platform::freertos_arm_profile, tin::platform::zephyr_arm_profile, tin::platform::qnx7_profile, and tin::platform::safety_profile for deployment profiles.
• tin::platform::compiler_satisfies_profile<Profile>() and tin::platform::enforce_compiler_profile<Profile>() for compiler-policy checks.

See embedded_framework.md for target integration guidance.

Example: Check A Target Profile

#include "tin/platform.h"
 
using HostTarget = tin::platform::host_linux_profile;
 
static_assert(HostTarget::heap_allowed);
static_assert(HostTarget::exceptions_allowed);
static_assert(HostTarget::tick_driven_time);
static_assert(tin::platform::compiler_satisfies_profile<HostTarget>());

Embedded targets can name a stricter profile and enforce it in a target-specific translation unit:

#include "tin/platform.h"
 
using EmbeddedTarget = tin::platform::bare_metal_arm_profile;
 
static_assert(!EmbeddedTarget::heap_allowed);
static_assert(!EmbeddedTarget::exceptions_allowed);
static_assert(EmbeddedTarget::tick_driven_time);
 
consteval void check_target() {
    tin::platform::enforce_compiler_profile<EmbeddedTarget>();
}

These checks keep build flags aligned with the deployment profile. Heap policy is also enforced through resource contracts and no-allocation checks because C++ does not expose a portable compiler macro for heap use.

Example: Target Adapter Boundary

Target-specific code should convert platform facts into runtime inputs before they reach behavior definitions:

#include <cstdint>
#include "tin/runtime.h"
 
struct TickElapsed {
    tin::tick_count count{};
};
 
template<typename Runtime>
void systick_elapsed(Runtime& runtime, tin::tick_count elapsed) {
    tin::dispatch_context context{
      .tick = elapsed.value,
      .sequence = 0U,
    };
 
    (void)context;
    (void)runtime.send_event(TickElapsed{ .count = elapsed });
}

The platform adapter owns interrupt, timer, and OS details. The runtime and HSM receive explicit typed events and integer tick metadata.

Working With tio

thal does not need to invent a separate device vocabulary. It can implement the portable contracts named by tio, then connect target events to tin runtime work.

Use tio when you are describing what a driver-shaped object can do. Use thal when you are deciding how that object is backed on a deployment target.

#include "tin/io.h"
#include "tin/platform.h"
#include "tin/runtime.h"
 
struct Stm32BatteryAdc {
    tin::io::adc_sample read();
};
 
static_assert(tin::io::adc<Stm32BatteryAdc>);
 
using Target = tin::platform::host_linux_profile;
static_assert(tin::platform::compiler_satisfies_profile<Target>());
 
tin::channel<tin::io::adc_sample, 8> battery_samples;
 
void adc_conversion_complete(Stm32BatteryAdc& adc) {
    (void)battery_samples.try_send_from_isr(adc.read());
}

Here the ADC object satisfies a tio concept. The target profile, wake path, ISR-safe send path, and compiler policy are thal concerns. A bare-metal build would name tin::platform::bare_metal_arm_profile in its target-specific translation unit.