KRN-OBJ - Kernel Objects, Lifecycle, and Storage¶

Documentation revision: 2026-10-14 (ADR-039; M1 amendment log). Existing status dates record original design acceptance, not validation of the revised wording. New implementation obligations remain Proposed until implemented and verified.

Group KRN-OBJ. Design: docs/specs/SPEC-009-objects-capabilities-and-storage.md. Related groups: KRN-CAP (handles and rights), KRN-WAIT (flush on destroy), KRN-PART (restart), BLD (storage generator), OBS (debug descriptor).

KRN-OBJ-001 to 005 originate in docs/architecture/03-kernel-architecture.md §7.4 (004 and 005 added by R-003 and ADR-032). All are restated here as the authoritative copy. New requirements start at 006.

Requirements¶

KRN-OBJ-001 Destroy with waiters¶

Statement. Destroying an object with waiters is a kernel fault in checked builds unless the object was created with ABORT_WAITERS, in which case every waiter wakes with DESTROYED. Rationale. ADR-020: lifecycle bugs are caught; deliberate teardown is explicit. Status. Accepted 2026-10-07 Verification. Test: wait/destroy_abort_waiters, misuse/destroy_with_waiters; model scenario destroy_with_waiters. Trace. SPEC-009 §6; SPEC-004 §6.7; ADR-020

KRN-OBJ-002 Generation bump on destroy¶

Statement. After destruction, the object’s generation shall be bumped so stale capabilities fail validation in profiles that check them. Rationale. Use-after-destroy becomes EMB_ESTALE instead of corruption. Status. Accepted 2026-10-07 Verification. Test: obj/stale_after_destroy (INDEXED and TABLE models). Trace. SPEC-009 §3.2, §3.3, §6

KRN-OBJ-003 Caller owns storage¶

Statement. Object storage ownership belongs to whoever provided it; the kernel never frees caller storage. Rationale. No allocator in the kernel path. Status. Accepted 2026-10-07 Verification. Analysis: no free call in kernel/; Test: storage reusable after destroy. Trace. SPEC-009 §5, §6

KRN-OBJ-004 System freeze¶

Statement. emb_system_freeze() shall, once called, make every create and destroy operation fail with EMB_EPERM (fault in checked builds) for the rest of the run; the isolated reference configuration shall call it at the end of initialization. Rationale. uC/OS-III’s safety-critical start; a frozen object set is what a certification argument wants. Status. Accepted 2026-10-07 Verification. Test: obj/freeze_blocks_init_destroy; isolated configuration review. Trace. SPEC-009 §6

KRN-OBJ-005 Thread and partition generations¶

Statement. Thread and partition handles shall carry a generation in every profile that checks generations; a wait on a handle whose generation changed because of a restart shall complete with EMB_ESTALE. Rationale. ADR-032: restarts are visible to peers. Status. Accepted 2026-10-07 Verification. Isolated-profile test part/join_restarted_thread_estale; model scenario (SPEC-010). Trace. SPEC-009 §6; ADR-032

KRN-OBJ-006 Common header¶

Statement. Every object shall begin with the header of SPEC-009 §2 (type_tag, lifecycle, flags, and the configured optional fields); fields not configured shall occupy no storage; the tiny release header shall be one byte. Rationale. One place for validation, registry, binding, and naming; zero cost where not used. Status. Accepted 2026-10-07 Verification. Analysis: _Static_assert on header size per configuration; footprint test. Trace. SPEC-009 §2

KRN-OBJ-007 Lifecycle states¶

Statement. Objects shall move UNINIT to ACTIVE at init, ACTIVE to DESTROYING to UNINIT at destroy; init on active storage shall be EMB_EEXIST (fault in checked builds); operations on a DESTROYING object shall return EMB_ESTATE. Rationale. Double init and destroy races have defined outcomes. Status. Accepted 2026-10-07 Verification. Test: misuse/double_init, SMP test obj/op_during_destroy_estate. Trace. SPEC-009 §6

KRN-OBJ-008 Generated storage types¶

Statement. <emb/storage.h> shall be generated from a layout probe compiled for the target with the final configuration and read with the toolchain’s object reader; kernel sources shall statically assert the real sizes and alignments against it; the header shall carry the configuration hash and a mismatch shall fail the build. Rationale. ADR-006 without mirrored structs or exposed layouts. Status. Accepted 2026-10-07 Verification. Build test: a deliberately stale header fails to build; Analysis: generator review. Trace. SPEC-009 §5.1; ADR-006; BLD-007

KRN-OBJ-009 Init table¶

Statement. _DEFINE macros shall register objects in the bracketed section .emb_init_table; emb_kernel_init() shall construct them in link order before scheduler start; EMB_INIT_AFTER shall order dependent objects; the mechanism shall use the port’s supported section/table mechanism; M1 AVR requires the board linker script to bracket flash entries (A8). Rationale. Static objects without hand-written init code, on AVR too (09 §7). Status. Accepted 2026-10-07 Verification. Test: init-table construction during emb_kernel_init() on every port including AVR. Trace. SPEC-009 §5.2; SPEC-001 §6.4

KRN-OBJ-010 Type-specific destroy conditions¶

Statement. Destroy shall be refused with EMB_EBUSY (fault in checked builds) for an owned mutex, a pool with outstanding blocks, a timer with a pending or running callback, a work queue with items, and a thread that is not inactive or terminated-and-reusable. Rationale. The kernel never leaves a dangling owner. Status. Accepted 2026-10-07 Verification. Test: misuse/destroy_* per type. Trace. SPEC-009 §6, §8

KRN-OBJ-011 Names and registry¶

Statement. With CONFIG_EMB_OBJ_NAMES objects shall keep their attribute name by pointer; with CONFIG_EMB_OBJ_LIST every active object shall be on a per-type list iterable under the scheduler lock; the debug descriptor shall export header offsets, type tags, list heads, and the registry or capability table layout. Rationale. Debuggers and statistics enumerate objects without symbols (ADR-011). Status. Accepted 2026-10-07 Verification. Test: debug descriptor consumer lists every object of the conformance run. Trace. SPEC-009 §7; OBS-008

KRN-OBJ-012 No flash-resident objects in 1.0¶

Statement. Kernel objects shall live in RAM and be constructed at boot; no const-initializer form of an object shall be part of the public API in 1.0. Rationale. A const form would expose the layout the storage type hides. Status. Accepted 2026-10-07 Verification. Analysis: header review. Trace. SPEC-009 §5.3, §12.5

KRN-OBJ-013 Trace¶

Statement. Object init and destroy (with the number of waiters flushed), capability changes, and system freeze shall be trace events. Rationale. Lifecycle debugging. Status. Accepted 2026-10-07 Verification. Test: trace decoder. Trace. SPEC-009 §9; OBS-005