HW requirements¶
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 Trace: SPEC-014 §3 to §6; ADR-004 |
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 |
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 |
Importers for CMSIS-SVD and DeviceTree source shall exist to bootstrap SoC and board descriptions; the SVD importer builds on EmbCC’s 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 |
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 Trace: SPEC-014 §6, §9 |
From the same region model, the generator shall emit both a GNU ld linker script and an 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 |
Descriptions shall be YAML 1.2 files of kind 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 |
A SoC description shall carry 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 |
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 |
The generator shall emit 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 |
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 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 |
Importers shall produce drafts with 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 |
Generated outputs shall be sorted, free of timestamps, and stamped with the generator version, schema version, and input hashes; Rationale: HW-003 made checkable. Status: Accepted 2026-10-07 Verification: Two generator runs produce identical outputs; stamp fields present. Trace: SPEC-014 §9 |
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 |
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 Trace: SPEC-014 §4, §6; TEST-012 |