# KRN-OBJ requirements ::::{req} Destroy with waiters :id: KRN-OBJ-001 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Generation bump on destroy :id: KRN-OBJ-002 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Caller owns storage :id: KRN-OBJ-003 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} System freeze :id: KRN-OBJ-004 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md `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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Thread and partition generations :id: KRN-OBJ-005 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Common header :id: KRN-OBJ-006 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Lifecycle states :id: KRN-OBJ-007 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Generated storage types :id: KRN-OBJ-008 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md `` 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Init table :id: KRN-OBJ-009 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md `_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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Type-specific destroy conditions :id: KRN-OBJ-010 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Names and registry :id: KRN-OBJ-011 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md :links: OBS-008 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} No flash-resident objects in 1.0 :id: KRN-OBJ-012 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md 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 [Normative source](../../requirements/KRN-OBJ.md). :::: ::::{req} Trace :id: KRN-OBJ-013 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-OBJ.md :links: OBS-005 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 [Normative source](../../requirements/KRN-OBJ.md). ::::