Public API reference — 0.1.0 stable surface¶

The application-facing API and its stability contract for the 0.1.0 development release. This is the single reference for what an app may call and what it may rely on; the authoritative per-symbol contract lives in the headers themselves (kernel/*.h, hal/*.h), which this doc indexes.

How to read this¶

Header tiers

Tier	Headers	Meaning
A — application API	`tk_kernel.h`, `tk_sem.h`, `tk_mutex.h`, `tk_cond.h`, `tk_spinlock.h`, `tk_seqlock.h`, `tk_status.h`, `tk_types.h`, `tk_time.h` + `hal/{tk_console,tk_board,tk_dio,tk_dio_irq,tk_uart,tk_port,tk_mcu}.h`	what an app includes
B — tooling / observability	`tk_trace.h`, `tk_det.h`	trace tools + a DET hook; the interface is stable, details experimental
Internal — NOT the API	`tk_kernel_sync.h` (Tier-C extension for library authors), `tk_stack.h` (placeholder), the `_internal.h` / `_port.h`	live in `kernel/` but carry a “not the application API” banner

Annotation tags (in the headers)

[rt] — callable at runtime from a thread, including an unprivileged one (traps through the syscall path).
[setup] — privileged/setup-only (before tk_kernel_start, or from a system thread).
[override] — a weak seam you provide (app or board), not a call-in API; the kernel calls it.
[experimental] — signature or semantics may still change; NOT frozen for 0.1.0.

Stability: everything below is STABLE (frozen for 0.1.0) unless marked [experimental]. Frozen means it will not change without a deprecation. The current experimental set is the WORLD security axis, the INSTANCE supervisor-fence override seams, and the thread-introspection snapshot — surfaces whose backing feature is not yet proven on a shipping board.

Threads (`tk_kernel.h`)¶

Symbol	Tag	Contract
`tk_thread_create(fn, arg, stack, cells, prio) → tk_thread_t*`	`[setup/rt]`	positional create; NULL if the pool is full
`tk_thread_create_in(k, …, out) → tk_thread_t*`	`[setup]`	create into a specific instance
`tk_thread_spawn(&t, &attr, fn, arg) → tk_status_t`	`[setup]`	attr create (pthread_create shape)
`tk_thread_spawn_in(k, &t, &attr, fn, arg) → tk_status_t`	`[setup]`	attr create into an instance
`tk_thread_attr_init / setstack / setpriority / setdetachstate`	`[setup]`	attribute builders (pthread_attr_* shape)
`tk_thread_yield()` · `tk_thread_sleep_ms(ms)` · `tk_sleep_ms(ms)`	`[rt]`	yield / sleep (the last is the one aliased short form)
`tk_thread_exit(rv)` · `tk_thread_join(t, &rv)` · `tk_thread_detach(t)`	`[rt]`	exit (noreturn) / join+reap / detach
`tk_thread_self()` · `tk_thread_id(t)` · `tk_thread_kernel(t)`	`[rt]`	own handle / stable id / owning instance
`tk_thread_set_quantum / set_privileged / set_affinity / pin / set_deadline`	`[setup]`	per-thread config (affinity `#if TK_FEAT_AFFINITY`, deadline `#if TK_CONFIG_ENABLE_EDF`)
`tk_thread_set_name(t, name)`	`[setup]`	attach a name (no-op without a trace/introspect build)
`tk_kernel_thread_snapshot(out, max)` · `_in` · `struct tk_thread_info`	`[rt]` `[experimental]`	ps/top snapshot; record shape may change

Types: tk_thread_fn = void*(*)(void*) (pthread-shaped), tk_thread_attr_t, enum tk_thread_state, enum tk_thread_detachstate. Constants: TK_PRIO_IDLE/MIN/MAX, TK_CORE(n), TK_THREAD_STACK(name, size).

Kernel lifecycle & instances (`tk_kernel.h`)¶

Symbol	Tag	Contract
`tk_kernel_init()` · `tk_kernel_start()`	`[setup]`	init once; enter the scheduler (no return on a switching port)
`tk_kernel_set_idle_hook / set_sched_policy / set_preempt_mode` (+ `_in`)	`[setup]`	kernel config (bare = default instance)
`tk_kernel_define(owned_cores, name, out) → tk_kernel_t*`	`[setup]`	declare an AMP/SMP-subset island
`tk_kernel_set_ram(k, base, size)` · `tk_kernel_set_trusted(k)`	`[setup]`	island private arena (C3-B) / trusted-monitor escape hatch
`tk_kernel_default / find / count / at`	`[setup]`	instance-handle ergonomics
`tk_kernel_self()` · `tk_kernel_name(k)` · `tk_kernel_owned_cores(k)`	`[rt]`	this-core instance / name / core mask
`tk_kernel_isolation()`	`[rt]`	the HW isolation boundary this build enforces
`tk_kernel_liveness_check(hard, soft)` · `tk_kernel_now_ms_in(k)`	`[rt]`	cross-island stall poll / a specific instance’s clock
WORLD axis: `tk_kernel_set_world / world / launch_secondary`, `tk_world_t`, `tk_fallback_t`	`[experimental]`	TrustZone-AMP security attribution — no shipping board realizes it yet
Override seams: `tk_kernel_on_stall`, `tk_watchdog_kick`, `tk_core_unclaimed`, `tk_instance_fence_reject`, `board_instance_fence_apply`, `board_world_protect`, `board_core_release`	`[override]`	weak; you/the board provide them

Synchronization¶

Header	Stable surface
`tk_mutex.h`	`tk_mutex_create(_in)`, `tk_mutex_init(&h, &attr)` (pthread_mutex_init shape), `tk_mutex_lock/unlock/lock_timeout`, `tk_mutexattr_init/settype/setprotocol`; `TK_MUTEX_{NORMAL,RECURSIVE,ERRORCHECK}`, `TK_MUTEX_PRIO_{NONE,INHERIT}`
`tk_sem.h`	`tk_sem_create(_in)`, `tk_sem_pend/post/pend_timeout`, `tk_sem_set_name`; `TK_SEM_INVALID`
`tk_cond.h`	`tk_cond_create(_in)`, `tk_cond_wait/wait_timeout/signal/broadcast`; `TK_COND_INVALID`
`tk_spinlock.h`	`tk_spin_init/lock/unlock/trylock` (SMP, `static inline`, value-typed key)
`tk_seqlock.h`	`tk_seq_init/write_begin/write_end/read_begin/read_retry` (read-mostly)

Handles (tk_sem_t / tk_mutex_t / tk_cond_t) are opaque int16_t into a static kernel pool; [rt] for the operate calls, [setup] for create/init/set_name.

Time (`tk_time.h`)¶

tk_time_init() [setup]; tk_time_ms() · tk_time_us() · tk_kernel_now_ms() [rt]. tk_kernel_now_ms is a second name for tk_time_ms kept for the scheduler/EDF timebase.

HAL (`hal/*.h`)¶

Minimal, stable contract (a status-returning / UART-RX layer is a compatible future add): tk_board_init; tk_console_init + tk_print / tk_print_u32 (+ weak tk_console_lock/unlock); tk_dio_read/write/flip (channel + pin) with TK_DIO_LOW/HIGH; tk_dio_irq_* (edge → callback); tk_uart_init/write/setup; tk_port_init/config_pin with tk_dir_t/tk_pull_t; tk_mcu_init / tk_mcu_clock_hz. The HAL uses its own tk_*_channel_t id types and does not carry the [rt]/[setup] scheme (that vocabulary is kernel-only).

Shared types¶

tk_status.h — tk_status_t {TK_OK, TK_ERR_PARAM, TK_ERR_BUSY, TK_ERR_STATE, TK_ERR_TIMEOUT, TK_ERR_UNSUPPORTED, TK_ERR}. tk_types.h — tk_stack_cell_t (the addressable stack cell, ADR 0001).

POSIX / pthreads¶

The threads + mutex + cond surface is pthread-shaped (not compliant). An opt-in shim compat/pthread.h maps pthread_{create,join,detach,exit,self,equal}, pthread_attr_*, pthread_mutex_*/mutexattr, pthread_cond_* onto tk_*; the demo examples/pthread_api proves it. Full analysis: docs/evaluation/standards-api-ergonomics.md.

Compile-time configuration¶

Knobs (TK_CONFIG_*) and derived capability flags (TK_FEAT_*, TK_ISOLATION_*, TK_ARCH_*) are transitively public through tk_kernel.h. Each carries a labelled contract block in kernel/tk_config.h — the single source of truth for values, defaults, requirements, and effects.

Naming notes (frozen for 0.1.0)¶

Three construction verbs are deliberate, not inconsistent: create (positional convenience), spawn (attr form, pthread_create shape), define (a kernel instance).
tk_sleep_ms is the single intentional short alias (ADR 0002 §8); yield/exit/join keep tk_thread_.
The _in suffix consistently marks the instance-targeted twin of a default-instance call.