# ARCH-AVR - ATmega328P Port

**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 `ARCH-AVR`. Design: `docs/specs/SPEC-012-atmega328p-port.md`. Related groups: PORT (the contract), KRN-IRQ, KRN-TIM, KRN-SCH (table scheduler), KRN-MEM, FLT, SIM, TEST.

New group; numbering starts at 001.

---

## Requirements

### ARCH-AVR-001  Manifest and tiny defaults
**Statement.** The AVR port shall declare 8-bit words, 16-bit pointers, byte stack alignment, a 37-byte context frame, no nesting, no zero-latency class, no compare-and-swap, no interrupt stack, no protection, no fault entry, and tickless limited to idle modes; the tiny defaults (table scheduler, 32-bit time, 8-bit notifications, no system work queue, no idle thread) shall be mandatory on it.
**Rationale.** SPEC-012 §2; ADR-036.
**Status.** Accepted 2026-10-07
**Verification.** Manifest schema check; configuration test refusing the isolated profile on AVR.
**Trace.** SPEC-012 §2

### ARCH-AVR-002  One frame layout
**Statement.** The thread-context switch, the interrupt epilogue switch, and the initial frame shall use the single 35-byte frame layout (37-byte call/context reserve) of SPEC-012 §4.1 (return address, `r0`, `SREG`, `r1`, `r2..r31`), so that an interrupt-exit switch is an exchange of stack pointers.
**Rationale.** One switch path (PORT-004) and the cheapest possible P1 on a core without an interrupt stack.
**Status.** Accepted 2026-10-07
**Verification.** Test: `arch/avr/frame_layout`, `arch/avr/switch_from_isr_and_thread_interoperate`.
**Trace.** SPEC-012 §4

### ARCH-AVR-003  Atomic launch and switch tail
**Statement.** The switch and launch sequences shall restore the incoming SREG and r0 before `ret`; M1 uses `out SREG; pop r0; ret`. A physical pending-interrupt test shall establish coherent context throughout that tail; a one-instruction enable delay shall not be used to claim the intervening pop is absent or the return necessarily precedes IRQ entry (A27).
**Rationale.** The actual restore tail and pending IRQ entry must be validated together; the historical out/ret-only description did not match the assembly.
**Status.** Accepted 2026-10-07
**Verification.** Test: `arch/avr/launch_with_pending_interrupt`.
**Trace.** SPEC-012 §4.2, §4.3

### ARCH-AVR-004  Interrupt prologue, epilogue, and reserve
**Statement.** `EMB_ISR` shall save the full frame with `I` forced set in the saved `SREG`, run the body with interrupts masked, and switch at exit when a reschedule is pending and the scheduler is unlocked; `EMB_ISR_RAW` shall be a `signal` handler that may not call the kernel; every thread stack shall include `CONFIG_EMB_AVR_ISR_STACK_RESERVE` (default 64 bytes), documented per release from supported compiler stack reports plus call-graph/disassembly accounting of naked routines; avr-gcc cannot report those routines with `-fstack-usage`.
**Rationale.** SPEC-002 §6.2, §7.2 on this core.
**Status.** Accepted 2026-10-07
**Verification.** Test: `arch/avr/isr_frame`, `arch/avr/isr_reserve_check`; documentation review.
**Trace.** SPEC-012 §4.4, §5

### ARCH-AVR-005  Timer1 modes and latency
**Statement.** The default tick shall be an exact 1 ms Timer1 CTC interrupt (prescaler 64, `OCR1A = 249` at 16 MHz); tickless shall use Timer1 free-running at prescaler 256 with a 1.048 s `MAX_INTERVAL`; arming latency shall be measured at init; `emb_arch_cycles` shall be a prescaled 32-bit count with its resolution documented; deep sleep shall be `EMB_ENOTSUP` until a tick-loss policy exists.
**Rationale.** SPEC-003 §13; KRN-TIM-036.
**Status.** Accepted 2026-10-07
**Verification.** HIL test: tick exactness over one minute against the host clock; `arch/avr/tickless_hop`; latency measurement test.
**Trace.** SPEC-012 §7

### ARCH-AVR-006  Footprint budget
**Statement.** The tiny reference configuration on this port shall fit the T1 and T2 targets: kernel text at most 4 KB at `-Os` on EmbCC and avr-gcc, kernel static RAM at most 64 bytes, TCB at most 32 bytes; the footprint test shall enforce them from the map file.
**Rationale.** R-003 §4.
**Status.** Accepted 2026-10-07
**Verification.** Footprint test in CI on both compilers.
**Trace.** SPEC-012 §8, §13

### ARCH-AVR-007  Flash constants and linker outputs
**Statement.** Kernel tables shall use `EMB_FLASH_CONST` and its accessors so that avr-gcc places them in program memory while EmbCC builds still work; large tables shall be compiled out on tiny; the generator shall emit the `embld` option set and a GNU ld script for the board from one region model.
**Rationale.** 09 §2 (`const` in RAM), §7 (no linker scripts on AVR); HW-006.
**Status.** Accepted 2026-10-07
**Verification.** Footprint comparison EmbCC versus avr-gcc; generator test for both outputs.
**Trace.** SPEC-012 §8

### ARCH-AVR-008  Robustness without faults
**Statement.** Checked builds on this port shall enable the switch-out stack guard check, the interrupt-reserve check, and the software watchdog service; a kernel fault shall write the small crash record to `.noinit` and reset through the watchdog by default.
**Rationale.** No fault hardware; the watchdog and the guards are the only safety nets.
**Status.** Accepted 2026-10-07
**Verification.** Test: `arch/avr/guard_detects_overflow`, `arch/avr/crash_record_survives_wdt_reset`.
**Trace.** SPEC-012 §8, §9; FLT-001, FLT-004

### ARCH-AVR-009  Debug and emulation path
**Statement.** Symbolic debugging shall use the qualified avr-gcc reference build until the EmbCC RTOS debugging path is qualified; the EmbCC build shall be verified by the conformance suite under QEMU and on the `arduino_uno` board, and timing from emulation shall never be published.
**Rationale.** EmbCC's AVR DWARF and remote layout are now implemented (09 §7/§9, reviewed 2026-10-14), but tool capability does not replace RTOS target/session qualification (SIM-002, SIM-003). The original acceptance date below is design status, not evidence that those runs passed.
**Status.** Accepted 2026-10-07
**Verification.** CI: QEMU AVR run of the conformance suite on both compilers; HIL run on the Uno.
**Trace.** SPEC-012 §10, §12

### ARCH-AVR-010  Board description
**Statement.** `boards/arduino/arduino_uno.yaml` shall describe the 16 MHz crystal, the USART0 console, the user LED, and the flash partitions leaving Optiboot's 512 bytes reserved; board init shall configure only the console and the LED.
**Rationale.** A new board on this SoC is a description file (01 §6).
**Status.** Accepted 2026-10-07
**Verification.** Generator test; boot test on the board.
**Trace.** SPEC-012 §11