PORT requirements

Requirement: Port manifest PORT-001

status: Accepted evidence: not evaluated design_source: requirements/PORT.md

Every port shall declare its properties and feature flags in arch/<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.

Requirement: Context on the thread stack 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.

Requirement: Startup entry points 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.

Requirement: Context init and single switch path 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.

Requirement: Interrupt entry, exit, and controller operations 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.

Requirement: Timer and cycle counter contract 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.

Requirement: Atomics through the portability layer 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.

Requirement: Atomic idle 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.

Requirement: Stack rules and checks 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.

Requirement: Fault entry and decode 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.

Requirement: Protection and trap hooks 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.

Requirement: Debug descriptor contribution PORT-012

status: Accepted evidence: not evaluated design_source: requirements/PORT.md links outgoing: 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.

Requirement: Toolchain rules for port code 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.

Requirement: Port deliverables 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/<arch>.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.