# PORT requirements ::::{req} Port manifest :id: PORT-001 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md Every port shall declare its properties and feature flags in `arch//arch.yaml` (word size, endianness, stack rules, nesting, zero-latency class, compare-and-swap, interrupt stack, hardware stack limit, protection model, lazy FPU, cycle counter, tickless, SMP, trap kind, fault entry, TCB extension); the configuration shall derive `EMB_ARCH_HAS_*` from it and refuse kernel features the port cannot support. **Rationale:** The contract is checkable data, not folklore. **Status:** Accepted 2026-10-07 **Verification:** Schema validation of every manifest; configuration tests for refused combinations. **Trace:** SPEC-011 §2 [Normative source](../../requirements/PORT.md). :::: ::::{req} Context on the thread stack :id: PORT-002 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A thread's register context shall be saved on its own stack; the TCB shall hold only the saved stack pointer and the port's declared extension bytes. **Rationale:** Smallest TCB; kernel layout independent of the register set. **Status:** Accepted 2026-10-07 **Verification:** Analysis: `emb_arch_tcb_t` definition per port; footprint test. **Trace:** SPEC-011 §3 [Normative source](../../requirements/PORT.md). :::: ::::{req} Startup entry points :id: PORT-003 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port shall provide `emb_arch_early_init`, `emb_arch_init`, and a non-returning `emb_arch_kernel_start` with the responsibilities of SPEC-011 §4, following the startup form of 09 §8 for its target. **Rationale:** SoC startup and the kernel need fixed hooks. **Status:** Accepted 2026-10-07 **Verification:** Test: `arch/boot_sequence` on each port. **Trace:** SPEC-011 §4 [Normative source](../../requirements/PORT.md). :::: ::::{req} Context init and single switch path :id: PORT-004 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md `emb_arch_context_init` shall build a frame that enters `embk_thread_launch(entry, arg)`, which calls the entry and exits with code 0; `emb_arch_switch_final` shall switch without saving the terminating context; `emb_arch_switch_out_done` shall prevent reuse until switch-out completes; `emb_arch_switch_to` shall save callee-saved state, exchange stack pointers, and resume; each architecture shall have exactly one switch path serving P1 and P2; the switch shall be a full memory barrier. **Rationale:** KRN-THR-005, KRN-MM-002, SPEC-002 §6. **Status:** Accepted 2026-10-07 **Verification:** Test: `arch/context_init_launch`, `arch/switch_roundtrip`, `arch/switch_from_isr_and_thread_interoperate`. **Trace:** SPEC-011 §5 [Normative source](../../requirements/PORT.md). :::: ::::{req} Interrupt entry, exit, and controller operations :id: PORT-005 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port shall implement the kernel-aware entry and exit sequence of SPEC-002 §6, `EMB_ISR` and `EMB_ISR_RAW`, the key-based critical-section primitives as always-inline functions with a memory clobber, `emb_arch_in_isr`, and the controller operations `enable`, `disable`, `set_level` (generic numbering), `clear_pending`, `pend_soft`, `is_enabled`, routing platform controllers from the generated tables. **Rationale:** SPEC-002 made these the kernel's expectations. **Status:** Accepted 2026-10-07 **Verification:** `tests/arch/irq_*`; KRN-IRQ tests on each port. **Trace:** SPEC-011 §6; SPEC-002 [Normative source](../../requirements/PORT.md). :::: ::::{req} Timer and cycle counter contract :id: PORT-006 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port shall implement the architecture timer contract of SPEC-003 §4 plus `emb_arch_timer_start_periodic`, `emb_arch_timer_set_latency_ticks`, `emb_arch_cycles`, and `emb_arch_cycles_hz`, and shall measure its arming latency at init unless the hardware description declares it. **Rationale:** KRN-TIM-020, 036. **Status:** Accepted 2026-10-07 **Verification:** `tests/arch/timer_*`: accuracy, MAX_INTERVAL hop, latency measurement, cycle monotonicity. **Trace:** SPEC-011 §7; SPEC-003 §4 [Normative source](../../requirements/PORT.md). :::: ::::{req} Atomics through the portability layer :id: PORT-007 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md Kernel atomics shall be C11 atomics through the portability layer; a port shall provide only barriers and its `cas` manifest flag, from which the wait protocol selects its transition implementation. **Rationale:** One source for EmbCC, GCC, and Clang (09 §5, §6). **Status:** Accepted 2026-10-07 **Verification:** Analysis: no hand-written exclusive-access asm in `arch/`; the wait-protocol tests pass with both transition forms. **Trace:** SPEC-011 §8; SPEC-004 §12; SPEC-005 §9 [Normative source](../../requirements/PORT.md). :::: ::::{req} Atomic idle :id: PORT-008 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md `emb_arch_idle` shall enable interrupts and wait for one without a window in which a wake-up can be lost; `emb_arch_sleep` shall enter the power core's mapped state. **Rationale:** A lost wake-up in idle is an unbounded latency. **Status:** Accepted 2026-10-07 **Verification:** Test: `arch/idle_no_lost_wakeup` with an interrupt pending at idle entry. **Trace:** SPEC-011 §9 [Normative source](../../requirements/PORT.md). :::: ::::{req} Stack rules and checks :id: PORT-009 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port shall declare stack alignment, minimum, and growth; implement the switch-out stack check and the hardware limit register where present; install or document the interrupt stack per SPEC-002 §7.2; and document handler and context frame sizes. **Rationale:** KRN-MEM-009 to 011, KRN-THR-023. **Status:** Accepted 2026-10-07 **Verification:** Test: `arch/stack_guard_detects_overflow`; documentation review. **Trace:** SPEC-011 §10 [Normative source](../../requirements/PORT.md). :::: ::::{req} Fault entry and decode :id: PORT-010 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port with fault hardware shall route every synchronous fault to `emb_arch_fault_entry`, decode the architecture state into `emb_fault_info_t`, classify the faulting context, call `embk_fault_dispatch`, and never return except through a recoverable-fault hook; a port without fault hardware shall say so in its manifest and documentation. **Rationale:** SPEC-002 §9; the crash record needs the decode. **Status:** Accepted 2026-10-07 **Verification:** Test: `arch/fault_decode` by injection on each fault class. **Trace:** SPEC-011 §11 [Normative source](../../requirements/PORT.md). :::: ::::{req} Protection and trap hooks :id: PORT-011 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port with protection hardware shall implement `emb_arch_mpu_init`, `emb_arch_mpu_apply`, `emb_arch_mpu_guard_set`, `emb_arch_user_access_ok`, `emb_arch_syscall_enter`, and `emb_arch_syscall_return` with the semantics of SPEC-010 §4 and §5; the region set encoding shall be the port's and opaque to the kernel. **Rationale:** Isolation mechanics belong to the port; policy to the kernel and generator. **Status:** Accepted 2026-10-07 **Verification:** Isolated-profile tests on each MPU port; `arch/syscall_roundtrip`. **Trace:** SPEC-011 §12; SPEC-010 [Normative source](../../requirements/PORT.md). :::: ::::{req} Debug descriptor contribution :id: PORT-012 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md :links: OBS-008 A port shall contribute the context frame layout, TCB extension layout, fault register layout, interrupt stack bounds, and its name and variant to the debug descriptor, and shall provide `emb_arch_breakpoint` and `emb_arch_trace_timestamp`. **Rationale:** ADR-011 needs architecture facts a debugger cannot infer. **Status:** Accepted 2026-10-07 **Verification:** Descriptor consumer test on each port. **Trace:** SPEC-011 §14; OBS-008 [Normative source](../../requirements/PORT.md). :::: ::::{req} Toolchain rules for port code :id: PORT-013 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md Port code shall follow the rules of SPEC-011 §15: `naked` functions or `.S` files for multi-block assembly, no labels in inline asm, no callee-saved registers in templates, always-inline critical sections with a memory clobber, no LTO, PIC, stack protector, or short enums, generated linker inputs, bracketed sections for registration, and documented workarounds for instruction vocabulary gaps. **Rationale:** One source for three compilers (09 §5, §7). **Status:** Accepted 2026-10-07 **Verification:** Build on EmbCC, GCC, and Clang for each port; CI grep for forbidden constructs. **Trace:** SPEC-011 §15; 09 [Normative source](../../requirements/PORT.md). :::: ::::{req} Port deliverables :id: PORT-014 :status: Accepted :evidence: not evaluated :design_source: requirements/PORT.md A port shall be complete only with its manifest, headers and sources, `docs/ports/.md` (frame layout, stack rules, latency figures, timer sources, fault classes, protection model, toolchain gaps), the `tests/arch/` group green, and the full kernel conformance suite green on the port. **Rationale:** A port without its evidence is not a port (01 §6). **Status:** Accepted 2026-10-07 **Verification:** Release checklist; CI gates. **Trace:** SPEC-011 §16 [Normative source](../../requirements/PORT.md). ::::