PORT - Compiler Portability and the Architecture Port Contract¶

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 PORT with two series: PORT-ABI (compiler portability, from v0.1 §21.5) and PORT (the architecture port contract, SPEC-011). Design: docs/specs/SPEC-011-architecture-port-contract.md; SPEC-001 §10 (compiler portability layer); docs/architecture/09-embcc-toolchain-profile.md. Related groups: KRN-IRQ, KRN-TIM, KRN-THR, KRN-PART, ARCH-AVR, SIM, BLD, OBS.

PORT-ABI-001 to 005 originate in the v0.1 specification (§21.5) and are restated here as the authoritative copy. PORT-001 onward are new.

Requirements¶

PORT-ABI-001 No EmbCC-specific extension in the public API¶

Statement. The public kernel API shall not require an EmbCC-specific language extension. Rationale. GCC and Clang builds are first-class (ADR-023). Status. Accepted 2026-10-07 Verification. Build matrix: public headers compile with -std=c11 -pedantic on GCC and Clang. Trace. SPEC-011 §15; SPEC-001 §10; v0.1 §21.5

PORT-ABI-002 Portability layer for attributes and builtins¶

Statement. Compiler-specific attributes and builtins shall be isolated behind portability interfaces. Rationale. No compiler conditionals scattered through generic code (v0.1 §21.2). Status. Accepted 2026-10-07 Verification. Analysis: CI grep rejects __attribute__ and __builtin_ outside include/emb/compiler/ and arch/. Trace. SPEC-011 §15; SPEC-001 §10

PORT-ABI-003 Documented and tested compiler matrix¶

Statement. Supported compiler and version combinations shall be documented and continuously tested where infrastructure permits. Rationale. Support is stated per architecture and version, not claimed globally (v0.1 §21.3). Status. Accepted 2026-10-07 Verification. Analysis: the matrix of 09 §11 is generated from CI results each release. Trace. 09 §11; 05 §2

PORT-ABI-004 Early detection of incompatible combinations¶

Statement. The build shall detect incompatible architecture, ABI, and configuration combinations as early as practical. Rationale. A refused configuration beats a wrong image. Status. Accepted 2026-10-07 Verification. Build tests: hard-float and soft-float mix, a kernel feature the port manifest lacks, a profile the port cannot support, each fails at configuration. Trace. SPEC-011 §2; BLD-007

PORT-ABI-005 Optimizations never change semantics¶

Statement. Toolchain-specific optimizations may improve performance but shall not change documented kernel semantics. Rationale. One conformance suite across compilers and optimization levels. Status. Accepted 2026-10-07 Verification. The conformance suite runs at -O0, -Os, and -O2 on every compiler of the matrix. Trace. 05 §4; 09 §7

PORT-001 Port manifest¶

Statement. 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

PORT-002 Context on the thread stack¶

Statement. 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

PORT-003 Startup entry points¶

Statement. 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

PORT-004 Context init and single switch path¶

Statement. 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

PORT-005 Interrupt entry, exit, and controller operations¶

Statement. 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

PORT-006 Timer and cycle counter contract¶

Statement. 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

PORT-007 Atomics through the portability layer¶

Statement. 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

PORT-008 Atomic idle¶

Statement. 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

PORT-009 Stack rules and checks¶

Statement. 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

PORT-010 Fault entry and decode¶

Statement. 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

PORT-011 Protection and trap hooks¶

Statement. 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

PORT-012 Debug descriptor contribution¶

Statement. 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

PORT-013 Toolchain rules for port code¶

Statement. 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

PORT-014 Port deliverables¶

Statement. 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