# HW - Hardware Description and Generator

Group `HW`. Design: `docs/specs/SPEC-014-hardware-description-schema.md`; `docs/architecture/04-platform-architecture.md` §1 (ADR-004, LOCKED). Related groups: KRN-PART (partition tables), KRN-CAP (initial capability tables), KRN-SYNC (static ceilings), KRN-OBJ (init table ordering), DRV (device tables, init order), BLD (generated files in the build), OBS (trace metadata), PORT (manifest cross-check).

HW-001 to 006 originate in `docs/architecture/04-platform-architecture.md` §1.3 (004 and 006 refined for EmbCC). All are restated here as the authoritative copy. New requirements start at 007.

---

## Requirements

### HW-001  Single source for hardware facts
**Statement.** Every peripheral instance, interrupt binding, clock setting, pin assignment, memory region, and flash partition shall originate in the hardware description.
**Rationale.** No hand-written board C for things the description knows (01 §6).
**Status.** Accepted 2026-10-07
**Verification.** Analysis: CI grep for register addresses and IRQ numbers in `boards/` and `soc/` C sources; review of generated outputs.
**Trace.** SPEC-014 §3 to §6; ADR-004

### HW-002  Schema validation with named errors
**Statement.** The hardware model shall be validated against a published schema before generation; validation errors shall name the file and node.
**Rationale.** Authors fix descriptions, not generator stack traces.
**Status.** Accepted 2026-10-07
**Verification.** Generator tests with malformed inputs; the error message names file and node path.
**Trace.** SPEC-014 §1, §7

### HW-003  Reproducible generated files
**Statement.** Generated files shall be reproducible and never edited by hand.
**Rationale.** BLD-004; drift between description and code is the failure this pipeline prevents.
**Status.** Accepted 2026-10-07
**Verification.** CI regenerates and diffs against the committed outputs.
**Trace.** SPEC-014 §9

### HW-004  SVD and DeviceTree importers
**Statement.** Importers for CMSIS-SVD and DeviceTree source shall exist to bootstrap SoC and board descriptions; the SVD importer builds on EmbCC's `embsvd` parser (09 §9).
**Rationale.** Authors curate rather than transcribe.
**Status.** Accepted 2026-10-07
**Verification.** Importer tests on the STM32F407 SVD and a Zephyr board DTS; the drafts validate and carry provenance.
**Trace.** SPEC-014 §8

### HW-005  Normalized JSON export
**Statement.** The normalized model shall be exported in a stable JSON form for tooling.
**Rationale.** EmbStudio, EmbDebug, the HIL runner, and the harness consume one artifact and never parse YAML.
**Status.** Accepted 2026-10-07
**Verification.** Schema for `hw.json`; consumer tests.
**Trace.** SPEC-014 §6, §9

### HW-006  Two linker outputs from one region model
**Statement.** From the same region model, the generator shall emit both a GNU ld linker script and an `embld` option set (`-Ttext`, `-Tdata`, `--rom-limit`); the two outputs shall be tested for agreement.
**Rationale.** Preserve a common layout with the legacy AVR option-set path. EmbCC now supports AVR scripts (09 §7, reviewed 2026-10-14); the existing two-output contract is retained, not justified by a current compiler limitation. Removing that compatibility output requires a separate reviewed amendment; the generator remains unimplemented.
**Status.** Accepted 2026-10-07
**Verification.** Generator test comparing the memory maps produced by both outputs for the Uno board.
**Trace.** SPEC-014 §6; SPEC-012 §8

### HW-007  Three description kinds and common conventions
**Statement.** Descriptions shall be YAML 1.2 files of kind `soc`, `board`, or `system` with a `schema_version`, validated by JSON Schema 2020-12, supporting unit suffixes, cross-file references, `extends` inheritance, provenance, `curated` marks, and `doc` text.
**Rationale.** One grammar for every hardware fact; DeviceTree's good ideas without its macro layer (R-002 §1).
**Status.** Accepted 2026-10-07
**Verification.** Schema files exist for the three kinds; conformance of the shipped descriptions.
**Trace.** SPEC-014 §1, §2

### HW-008  SoC and board content
**Statement.** A SoC description shall carry `arch`, `cpu`, `memory`, `interrupts`, and `peripherals` (clocks, DMA, flash, power, errata, debug optional) and shall reference a port manifest; a board description shall carry the SoC reference, oscillators, pins, devices, console, flash partitions, LEDs, buttons, probe hints, and defaults.
**Rationale.** SPEC-014 §3, §4 fix what the generator can rely on.
**Status.** Accepted 2026-10-07
**Verification.** Schema required fields; the STM32F407, RP2350, and ATmega328P descriptions validate.
**Trace.** SPEC-014 §3, §4

### HW-009  System description as the static source
**Statement.** The system description shall declare the profile, configuration overrides, partitions, kernel-partition threads and objects, ceiling mutexes with users, shares, trace and log configuration, and images; the generator shall derive kstore sizes, capability tables, ceilings, and init ordering from it.
**Rationale.** SPEC-009 §4.1, §5.2; SPEC-010 §2; SPEC-005 §3.4.
**Status.** Accepted 2026-10-07
**Verification.** Generator tests for a two-partition system; the isolated reference configuration is one.
**Trace.** SPEC-014 §5

### HW-010  Generated outputs
**Statement.** The generator shall emit `hw_config.h`, `soc_devices.c`, `soc_clocks.c`, `board_pins.c`, `regions.ld` and `embld.opts`, `partitions.c`, `caps_init.c`, `ceilings.h`, `init_order.c`, `Kconfig.board` and `Kconfig.system`, `board.md`, `hw.json`, `build_report.md`, and the CTF trace metadata, each as SPEC-014 §6 describes.
**Rationale.** The complete list is what downstream specifications depend on.
**Status.** Accepted 2026-10-07
**Verification.** Generator golden-file tests per output.
**Trace.** SPEC-014 §6

### HW-011  Semantic validation
**Statement.** The generator shall fail the build, naming file and node, on unresolved references, duplicate names, overlapping or misaligned regions or partitions, independently writable flash partitions sharing erase units or violating write/update alignment, duplicate or out-of-range interrupts, pin conflicts, clock cycles or bus overspeed, dependency cycles, partition hardware constraint violations, undeclared ceiling users, port manifest mismatches, inapplicable errata, and uncurated nodes under the `safety` attribute.
**Rationale.** Every rule here was a runtime bug somewhere else.
**Status.** Accepted 2026-10-07
**Verification.** One negative generator test per rule.
**Trace.** SPEC-014 §7

### HW-012  Importers produce drafts, never overwrites
**Statement.** Importers shall produce drafts with `imported_from` provenance and `todo` markers; re-import shall produce a diff for the author and shall never overwrite curated nodes.
**Rationale.** Curation is the value; tooling must not destroy it.
**Status.** Accepted 2026-10-07
**Verification.** Importer tests: re-import after curation leaves curated nodes intact and reports differences.
**Trace.** SPEC-014 §8

### HW-013  Determinism and stamps
**Statement.** Generated outputs shall be sorted, free of timestamps, and stamped with the generator version, schema version, and input hashes; `hw.json` shall carry the same stamps.
**Rationale.** HW-003 made checkable.
**Status.** Accepted 2026-10-07
**Verification.** Two generator runs produce identical outputs; stamp fields present.
**Trace.** SPEC-014 §9

### HW-014  Schema versioning and migration
**Statement.** Schema v0 is unstable until its own stable release and ships a migration tool for breaking changes; from that release the schema shall follow the API versioning policy.
**Rationale.** Descriptions are long-lived assets of users.
**Status.** Accepted 2026-10-07
**Verification.** Migration test on a v0 fixture at each breaking change.
**Trace.** SPEC-014 §10; SPEC-001 §11

### HW-015  Benchmark and tooling metadata
**Statement.** `hw.json` shall provide the board, SoC revision, clock, and timer-source fields the benchmark metadata record of 05 §4.4 requires, and the probe hints the HIL runner needs.
**Rationale.** One source for the numbers that make measurements comparable (R-003 §6).
**Status.** Accepted 2026-10-07
**Verification.** Harness metadata test reads them from `hw.json`.
**Trace.** SPEC-014 §4, §6; TEST-012