Core Requirements

This document tracks all functional and non-functional requirements for the Axion-HDL core tool. Testing and verification are automated via make test, which maps tests back to these requirement IDs.

Requirement Categories

Prefix	Category	Definition
AXION	Core Protocol	Core AXI4/AXI4-Lite register interaction and compliance.
AXI-LITE	Bus Protocol	Specific AXI4-Lite handshake and signaling rules.
PARSER	VHDL Parsing	Parsing of VHDL entities, signals, and @axion annotations.
XML-INPUT	XML Parsing	Parsing of XML register definition files.
YAML-INPUT	YAML Parsing	Parsing of YAML register definition files.
JSON-INPUT	JSON Parsing	Parsing of JSON register definition files.
GEN	Code Generation	Generation of VHDL register wrappers, C headers, and data formats.
ERR	Error Handling	Detection and reporting of invalid configurations or conflicts.
CLI	Interface	Command-line interface arguments and behavior.
CDC	Clock Crossing	Clock Domain Crossing synchronization logic.
ADDR	Addressing	Automatic and manual register address assignment.
STRESS	Performance	Handling of large modules, wide signals, and massive generation.
SUB	Subregisters	Support for packed registers (multiple fields in one 32-bit word).
DEF	Default Values	Support for reset values via DEFAULT attribute.
VAL	Validation	Validation of inputs, error visibility, and diagnostics.
EQUIV	Format Equivalence	Cross-format parsing and output equivalence.
AXION-TYPES	Typed AXI Ports	Optional typed AXI4-Lite port generation using axion_common_pkg record types.
HIER	Hierarchy	Centralized base address assignment and multi-instance generation via --hier flag.

---

1. Core Protocol (AXION)

ID	Definition	Acceptance Criteria	Test Method
AXION-001	Read-Only Register Read Access	A read transaction to a RO register address must return the signal value.	VHDL Simulation (vhdl.req.axion_001)
AXION-002	Read-Only Register Write Protection	A write transaction to a RO register address must be ignored (no signal change).	VHDL Simulation (vhdl.req.axion_002)
AXION-003	Write-Only Register Write Access	A write transaction to a WO register address must update the signal value.	VHDL Simulation (vhdl.req.axion_003)
AXION-004	Write-Only Register Read Protection	A read transaction to a WO register address must return 0x00000000 (or predictable value).	VHDL Simulation (vhdl.req.axion_004)
AXION-005	Read-Write Register Full Access	RW registers must be readable (return current value) and writable (update value).	VHDL Simulation (vhdl.req.axion_005)
AXION-006	Register Address Mapping	Registers must be mapped to their assigned offset addresses relative to base.	VHDL Simulation (vhdl.req.axion_006)
AXION-007	Base Address Offset Calculation	The module base address must be added to the register offset for final addressing.	VHDL Simulation (vhdl.req.axion_007)
AXION-008	Module Address Space Isolation	Transactions outside the module’s address range must be ignored or pass-through.	VHDL Simulation (vhdl.req.axion_008)
AXION-009	AXI Write Response Error Signaling	Write errors (e.g. invalid address) must assert BRESP with SLVERR.	VHDL Simulation (vhdl.req.axion_009)
AXION-010	AXI Read Response Error Signaling	Read errors must assert RRESP with SLVERR.	VHDL Simulation (vhdl.req.axion_010)
AXION-011	AXI Write Transaction Handshake	AWVALID/AWREADY, WVALID/WREADY, BVALID/BREADY handshakes must complete correctly.	VHDL Simulation (vhdl.req.axion_011)
AXION-012	AXI Read Transaction Handshake	ARVALID/ARREADY, RVALID/RREADY handshakes must complete correctly.	VHDL Simulation (vhdl.req.axion_012)
AXION-013	Read Strobe Signal Generation	Read strobe must assert for 1 cycle when a register is read.	VHDL Simulation (vhdl.req.axion_013)
AXION-014	Write Strobe Signal Generation	Write strobe must assert for 1 cycle when a register is written.	VHDL Simulation (vhdl.req.axion_014)
AXION-015	Write Enable Signal Generation	Write enable must assert on valid write data.	VHDL Simulation (vhdl.req.axion_015)
AXION-016	Byte-Level Write Strobe Support	Partial writes (via WSTRB) must update only appropriate bytes.	VHDL Simulation (vhdl.req.axion_016)
AXION-017	Synchronous Reset	Signal reset must occur synchronously on rising clock edge when reset_n is low.	VHDL Simulation (vhdl.req.axion_017)
AXION-018	Clock Domain Crossing	Signals crossing domains must pass through synchronizers (if enabled).	VHDL Simulation (vhdl.req.axion_018)
AXION-019	Documentation Generation	Helper documentation must be generated for register map.	VHDL Simulation (vhdl.req.axion_019)
AXION-020	Unaligned Address Access	Access to unaligned addresses (not 4-byte boundaries) should error or align.	VHDL Simulation (vhdl.req.axion_020)
AXION-021	Out-of-Range Address Access	Access to undefined offsets within base range returns SLVERR or DECERR.	VHDL Simulation (vhdl.req.axion_021)
AXION-022	Concurrent Read and Write Operations	Simultaneous Read and Write channels must operate independently.	VHDL Simulation (vhdl.req.axion_022)
AXION-023	Default Register Values	Registers must initialize to defined default values on reset.	VHDL Simulation (vhdl.req.axion_023)
AXION-024	Register Bit Field Support	Partial field updates must preserve other bits in the register.	VHDL Simulation (vhdl.req.axion_024)
AXION-025	Wide Signal Support	Signals >32 bits must span multiple consecutive registers.	VHDL Simulation (vhdl.req.axion_025x)
AXION-026	Multi-register access	Reads/Writes to parts of wide signals must correctly update specific bits.	VHDL Simulation (vhdl.req.axion_026x)
AXION-027	Existing File Overwrite	The tool must overwrite existing files in the output directory.	Python Unit Test (python.gen.overwrite)

2. Bus Protocol (AXI-LITE)

ID	Definition	Acceptance Criteria	Test Method
AXI-LITE-001	Reset State Requirements	On reset, outgoing valid/ready signals must be deasserted.	VHDL Simulation (vhdl.req.axi_lite_001)
AXI-LITE-002	Single Transfer Per Transaction	AXI-Lite does not support burst; burst length is always 1.	VHDL Simulation (vhdl.req.axi_lite_002)
AXI-LITE-003	VALID Before READY Dependency	VALID signals must not depend on READY signals to be asserted.	VHDL Simulation (vhdl.req.axi_lite_003)
AXI-LITE-004	VALID Stability Rule	Once VALID is asserted, it must remain high until READY is asserted.	VHDL Simulation (vhdl.req.axi_lite_004)
AXI-LITE-005	Write Address/Data Independence	Core must accept Address and Data phases in any order.	VHDL Simulation (vhdl.req.axi_lite_005)
AXI-LITE-006	Back-to-Back Transaction Support	Core handles transactions arriving immediately after previous one completes.	VHDL Simulation (vhdl.req.axi_lite_006)
AXI-LITE-007	Write Response Timing	BRESP must not be asserted until both WVALID and AWVALID have arrived.	VHDL Simulation (vhdl.req.axi_lite_007)
AXI-LITE-008	Read Response Timing	RVALID must not be asserted until ARVALID has arrived.	VHDL Simulation (vhdl.req.axi_lite_008)
AXI-LITE-014	Response Code Compliance	OKAY for success, SLVERR/DECERR for errors.	VHDL Simulation (vhdl.req.axi_lite_014)
AXI-LITE-015	Clock Edge Alignment	All outputs change on rising clock edge.	VHDL Simulation (vhdl.req.axi_lite_015)
AXI-LITE-016	Delayed READY Handling	Core waits indefinitely for READY to be asserted by master/slave.	VHDL Simulation (vhdl.req.axi_lite_016)
AXI-LITE-017	Early READY Handling	Core can assert READY before VALID is asserted.	VHDL Simulation (vhdl.req.axi_lite_017)

3. VHDL Parsing (PARSER)

ID	Definition	Acceptance Criteria	Test Method
PARSER-001	Basic entity name extraction and whitespace handling	Parser correctly identifies entity <name> regardless of whitespace.	Python Unit Test (parser.test_parser_001)
PARSER-002	Parse std_logic and std_logic_vector types	Correctly identifies signal width (1 for std_logic, N for vector).	Python Unit Test (parser.test_parser_002)
PARSER-003	Parse Access Modes and strobe flags	extracts RW/RO/WO and R_STROBE/W_STROBE from @axion comments.	Python Unit Test (parser.test_parser_003)
PARSER-004	Parse Attributes	Extracts BASE_ADDR, CDC_EN (flag/kv), CDC_STAGE key-values.	Python Unit Test (parser.test_parser_004)
PARSER-005	Parse Hex/Decimal addresses	Handles 0x10 and 16 as valid address inputs.	Python Unit Test (parser.test_parser_005)
PARSER-006	Parse Descriptions	Extracts description string from comments, handling quotes.	Python Unit Test (parser.test_parser_006)
PARSER-007	Exclude directories	Skips directories specified in exclude list.	Python Unit Test (parser.test_parser_007)
PARSER-008	Recursive scanning	Recursively finds .vhd files in subfolders.	Python Unit Test (parser.test_parser_008)
PARSER-009	signal_type Format Compatibility	The signal_type field in the register dict produced by VHDLParser must be parseable by downstream generators (CHeaderGenerator, DocGenerator) to extract the correct bit width.	Python Unit Test (parser.test_parser_009)

4. Code Generation (GEN)

ID	Definition	Acceptance Criteria	Test Method
GEN-001	VHDL Entity Naming and File Generation	Output file is named <module>_axion_reg.vhd and can be compiled.	Python Unit Test (gen.test_gen_001)
GEN-002	Architecture RTL and Signal Declarations	Defines architecture rtl and declares necessary internal signals.	Python Unit Test (gen.test_gen_002)
GEN-003	AXI Channel Signal Generation	Generates all standard AXI4-Lite interface ports.	Python Unit Test (gen.test_gen_003)
GEN-004	Register Direction (IN/OUT)	RO signals mapped to inputs, internal regs mapped to outputs.	Python Unit Test (gen.test_gen_004)
GEN-005	Read Strobe Port Generation	Generates output port <signal>_rd_strobe if requested.	Python Unit Test (gen.test_gen_005)
GEN-006	Write Strobe Port Generation	Generates output port <signal>_wr_strobe if requested.	Python Unit Test (gen.test_gen_006)
GEN-007	State Machine Logic	Includes AXI state machine (Idle, Read, Write, Resp).	Python Unit Test (gen.test_gen_007)
GEN-008	Address Decoder Logic	Generates case statement for address decoding.	Python Unit Test (gen.test_gen_008)
GEN-009	C Header Generation	Generates valid .h file with offset macros and structs.	Python Unit Test (gen.test_gen_009)
GEN-010	C Struct Definition	Generates typedef struct representing register map.	Python Unit Test (gen.test_gen_010)
GEN-011	XML Map Generation	Generates .xml file describing the register map.	Python Unit Test (gen.test_gen_011)
GEN-012	Markdown Documentation Generation	Generates .md file with register tables.	Python Unit Test (gen.test_gen_012)
GEN-013	YAML Map Generation	Generates {module}_regs.yaml with valid YAML syntax.	Python Unit Test (gen.test_gen_013)
GEN-014	JSON Map Generation	Generates {module}_regs.json with valid JSON syntax.	Python Unit Test (gen.test_gen_014)
GEN-015	HTML Documentation Generation	Generates styled register_map.html with embedded CSS.	Python Unit Test (gen.test_gen_015)
GEN-016	PDF Documentation Generation	Generates register_map.pdf file (optional, requires weasyprint).	Python Unit Test (gen.test_gen_016)
GEN-017	Address Range Calculation	Calculates and displays address range (start-end) for each module.	Python Unit Test (gen.test_gen_017)
GEN-018	Base Address Generic	VHDL entity includes BASE_ADDR generic used for offset calculation.	Python Unit Test (gen.test_gen_018)
GEN-019	C Header Width Propagation (YAML)	CHeaderGenerator._get_signal_width must correctly extract width from signal_type strings produced by the YAML parser (std_logic, std_logic_vector(N downto 0)). WIDTH and NUM_REGS macros must reflect the declared width.	Python Unit Test (gen.test_gen_019)
GEN-020	C Header Width Propagation (VHDL Annotation)	Same as GEN-019 but for signal_type strings produced by the VHDL-annotation parser ([N:0] format). WIDTH and NUM_REGS macros must reflect the declared width.	Python Unit Test (gen.test_gen_020)
GEN-021	C Header Struct Layout for Wide Signals	Registers wider than 32 bits must appear as multiple _reg0, _reg1 … members in the generated struct. Registers ≤ 32 bits must appear as a single member with no suffix.	Python Unit Test (gen.test_gen_021)
GEN-022	Markdown Width Column Accuracy (YAML)	The Width column in the generated register_map.md table must show the actual declared register width, not a hardcoded value, for registers defined via YAML.	Python Unit Test (gen.test_gen_022)
GEN-023	Markdown Width Column Accuracy (VHDL Annotation)	Same as GEN-022 but for registers defined via VHDL @axion annotations.	Python Unit Test (gen.test_gen_023)
GEN-024	Packed Register MASK/SHIFT Macros (YAML)	For packed (subregister) fields defined via YAML, the generated header must contain correct MASK and SHIFT #define macros matching each field’s bit_offset and width.	Python Unit Test (gen.test_gen_024)
GEN-025	Packed Register MASK/SHIFT Macros (VHDL Annotation)	Same as GEN-024 but for packed fields defined via VHDL @axion annotations with REG_NAME/BIT_OFFSET.	Python Unit Test (gen.test_gen_025)
GEN-026	Packed Register Container is 32-bit	A packed register container must appear as exactly one uint32_t member in the struct (no _reg0 split).	Python Unit Test (gen.test_gen_026)
GEN-027	VHDL Entity Port Width – YAML source	For registers defined via YAML, the generated VHDL entity port must use the declared width (e.g. std_logic for 1-bit, std_logic_vector(4 downto 0) for 5-bit). Must not default to 32-bit.	Python Unit Test (gen.test_gen_027)
GEN-028	VHDL Entity Port Width – VHDL-annotation source	Same as GEN-027 but for registers defined via VHDL @axion annotations.	Python Unit Test (gen.test_gen_028)

5. Error Handling (ERR)

ID	Definition	Acceptance Criteria	Test Method
ERR-001	Address Conflict Detection	Raises AddressConflictError if two registers share an address.	Python Unit Test (err.test_err_001)
ERR-002	Non-VHDL/Binary File Handling	Gracefully skips non-text files without crashing.	Python Unit Test (err.test_err_002)
ERR-003	Skipped Files	Skips files missing @axion or valid entities.	Python Unit Test (err.test_err_003)
ERR-004	Invalid Hex Address Reporting	Reports error for malformed hex strings.	Python Unit Test (err.test_err_004)
ERR-005	No Entity Declaration Handling	Handles files missing entity declarations.	Python Unit Test (err.test_err_005)
ERR-006	Duplicate Signal Detection	Detects and reports duplicate signal names within a module.	Python Unit Test (err.test_err_006)
ERR-007	Address Overlap Detection	Warns when multiple modules have overlapping address ranges.	Python Unit Test (err.test_err_007)

6. Command Line Interface (CLI)

ID	Definition	Acceptance Criteria	Test Method
CLI-001	Help Options (-h, –help)	Prints usage information and exits with 0.	Python Unit Test (cli.test_cli_001)
CLI-002	Version Option (–version)	Prints tool version and exits with 0.	Python Unit Test (cli.test_cli_002)
CLI-003	Source Path Options (-s, –source)	Accepts source files (.vhd, .vhdl, .xml, .yaml, .yml, .json) or directories with auto-detection by extension.	Python Unit Test (cli.test_cli_003)
CLI-004	Multiple Source Paths	Accepts multiple -s flags for any combination of files and directories.	Python Unit Test (cli.test_cli_004)
CLI-005	Output Directory Options (-o, –output)	Accepts output path argument.	Python Unit Test (cli.test_cli_005)
CLI-006	Exclude Options (-e)	Excludes matching patterns from processing.	Python Unit Test (cli.test_cli_006)
CLI-009	Invalid Source Handling	Returns error code if source path invalid.	Python Unit Test (cli.test_cli_009)
CLI-010	Output Directory Creation	Creates output directory if it doesn’t exist.	Python Unit Test (cli.test_cli_010)
CLI-011	YAML Output Flag (–yaml)	--yaml generates YAML register map output.	Python Unit Test (cli.test_cli_011)
CLI-012	JSON Output Flag (–json)	--json generates JSON register map output.	Python Unit Test (cli.test_cli_012)
CLI-013	Configuration File Support (-c, –config)	--config <file> loads settings (sources, excludes) from JSON file.	Python Unit Test (cli.test_cli_013)
CLI-014	Save Configuration to Persistent File	The tool must provide a mechanism to save the current configuration to a persistent file (e.g., .axion_conf).	GUI Integration Test
CLI-015	Auto-load Configuration	The tool must automatically load configuration from .axion_conf in the current working directory if it exists and no specific config file is provided via --config.	Python Unit Test (cli.test_cli_015)

[!NOTE] The -x/--xml-source option is deprecated but still supported for backward compatibility. Use -s/--source for all source types instead.

7. Clock Domain Crossing (CDC)

ID	Definition	Acceptance Criteria	Test Method
CDC-001	Configurable Stage Count	CDC_STAGE=N setting changes synchronizer depth.	Python Unit Test (cdc.test_cdc_001)
CDC-002	Default Stage Count	Defaults to 2 stages if not specified.	Python Unit Test (cdc.test_cdc_002)
CDC-003	Sync Signal Declaration	Internal sync signals declared in VHDL.	Python Unit Test (cdc.test_cdc_003)
CDC-004	Module Clock Port Generation	Generates module_clk port when CDC enabled.	Python Unit Test (cdc.test_cdc_004)
CDC-005	CDC Disable Behavior	No sync logic generated if CDC_EN is missing/false.	Python Unit Test (cdc.test_cdc_005)
CDC-006	Read-Only (RO) Path Synchronization	RO inputs synced to AXI clock domain.	Python Unit Test (cdc.test_cdc_006)
CDC-007	Read-Write (RW) Path Synchronization	RW outputs synced to module clock domain.	Python Unit Test (cdc.test_cdc_007)

8. Address Management (ADDR)

ID	Definition	Acceptance Criteria	Test Method
ADDR-001	Auto-assign Sequential Addresses	Assigns 0x00, 0x04, 0x08… automatically if unspecified.	Python Unit Test (addr.test_addr_001)
ADDR-002	Manual Address Assignment	ADDR=0xNN allows specific address placement.	Python Unit Test (addr.test_addr_002)
ADDR-003	Mixed Auto/Manual Assignment	Auto assignment skips manually assigned addresses.	Python Unit Test (addr.test_addr_003)
ADDR-004	Address Alignment	All addresses must be 4-byte aligned.	Python Unit Test (addr.test_addr_004)
ADDR-005	Conflict Detection	Manual assignment collision raises error.	Python Unit Test (addr.test_addr_005)
ADDR-006	Wide Signal Address Reservation	Signals >32 bits reserve multiple 4-byte slots.	Python Unit Test (addr.test_addr_006)
ADDR-007	Gap Preservation	Gaps created by manual addressing are preserved.	Python Unit Test (addr.test_addr_007)
ADDR-008	Base Address Offset Addition	Manual addresses are relative to module base.	Python Unit Test (addr.test_addr_008)

9. Stress Testing (STRESS)

ID	Definition	Acceptance Criteria	Test Method
STRESS-001	Support High Register Count	Can generate module with 100+ registers.	Python Unit Test (stress.test_stress_001)
STRESS-002	Support Very Wide Signals	Can handle 256-bit+ signals correctly.	Python Unit Test (stress.test_stress_002)
STRESS-003	Repeated Analysis Stability	Multiple runs produce consistent results.	Python Unit Test (stress.test_stress_003)
STRESS-004	Repeated Generation Stability	Generation is deterministic.	Python Unit Test (stress.test_stress_004)
STRESS-005	Random Address Patterns	Handles non-sequential manual addressing without error.	Python Unit Test (stress.test_stress_005)
STRESS-006	Boundary Value Handling	Robust to min/max address and width values.	Python Unit Test (stress.test_stress_006)

10. Subregisters (SUB)

ID	Definition	Acceptance Criteria	Test Method
SUB-001	Parse REG_NAME Attribute	Parser identifies REG_NAME to group signals.	Python Unit Test (sub.test_sub_001)
SUB-002	Parse BIT_OFFSET Attribute	Parser identifies start bit for fields.	Python Unit Test (sub.test_sub_002)
SUB-003	Group signals by REG_NAME	Signals with same REG_NAME are grouped into one 32-bit register.	Python Unit Test (sub.test_sub_003)
SUB-004	Auto-calculate Register Width	Register width determined by fields (always 32-bit container).	Python Unit Test (sub.test_sub_004)
SUB-005	Detect Bit Overlaps	Overlapping bit ranges raise BitOverlapError.	Python Unit Test (sub.test_sub_005)
SUB-006	Auto-pack signals	Fields without BIT_OFFSET pack sequentially.	Python Unit Test (sub.test_sub_006)
SUB-007	Subregister Field Width in Header (VHDL)	MASK and SHIFT macros generated for packed fields defined via VHDL @axion annotations must match the declared BIT_OFFSET and signal width exactly.	Python Unit Test (sub.test_sub_007)
SUB-008	Subregister Field Width in Header (YAML)	MASK and SHIFT macros generated for packed fields defined via YAML reg_name / bit_offset must match the declared bit_offset and width exactly.	Python Unit Test (sub.test_sub_008)
SUB-011	Backward Compatibility	Standard signals still processed correctly mixed with subregs.	Python Unit Test (sub.test_sub_011)

11. Default Values (DEF)

ID	Definition	Acceptance Criteria	Test Method
DEF-001	Parse DEFAULT Hex Value	DEFAULT=0x... parsed correctly.	Python Unit Test (def.test_def_001)
DEF-002	Parse DEFAULT Decimal Value	DEFAULT=100 parsed correctly.	Python Unit Test (def.test_def_002)
DEF-003	Validate Default fits Width	Value larger than signal width raises error/warning.	Python Unit Test (def.test_def_003)
DEF-004	Default to 0 if unspecified	Signals default to 0x0 if no attribute.	Python Unit Test (def.test_def_004)
DEF-009	Combine Subregister Defaults	Packed register default is OR-combination of field defaults.	Python Unit Test (def.test_def_009)
DEF-010	Backward Compatibility	Existing modules unaffected.	Python Unit Test (def.test_def_010)

12. Validation & Diagnostics (VAL)

ID	Definition	Acceptance Criteria	Test Method
VAL-001	Required Field Validation	Missing ‘module’ or other required fields in source files (YAML/JSON/XML) must be reported as Errors.	Python Unit Test (val.test_val_001)
VAL-002	Format Error Visibility	Parsing errors (malformed syntax) must be visible in Rule Check results.	Python Unit Test (val.test_val_002)
VAL-003	Logical Integrity Check	Validates integrity of loaded modules (e.g. non-empty register lists).	Python Unit Test (val.test_val_003)
VAL-004	Description Presence	Warns if registers are missing descriptions/documentation.	Python Unit Test (val.test_val_004)
VAL-005	Duplicate Module Name	Error if multiple modules share the same name.	Python Unit Test (val.test_val_005)
VAL-006	Numeric Attribute Validation	Invalid numeric values for base_addr, addr, width, bit_offset, and cdc_stage must be reported as Parsing Errors.	Python Unit Test
VAL-007	Generation Safety Lock	The tool must block all code and documentation generation if any analyzed module contains parsing errors.	Python Unit Test

13. XML Input (XML-INPUT)

ID	Definition	Acceptance Criteria	Test Method
XML-INPUT-001	XML File Detection	Parser detects and loads .xml files from directories.	Python Unit Test (xml_input.test_xml_input_001)
XML-INPUT-002	Module Name Extraction	Correctly extracts module attribute from root element.	Python Unit Test (xml_input.test_xml_input_002)
XML-INPUT-003	Base Address Parsing	Parses base_addr as hex string or decimal value.	Python Unit Test (xml_input.test_xml_input_003)
XML-INPUT-004	Register Definition Parsing	Parses <register> elements with name, addr, access, width attributes.	Python Unit Test (xml_input.test_xml_input_004)
XML-INPUT-005	Access Mode Support	Handles RO, RW, WO access modes (case-insensitive).	Python Unit Test (xml_input.test_xml_input_005)
XML-INPUT-006	Strobe Signal Support	Parses r_strobe and w_strobe attributes (“true”/”false”).	Python Unit Test (xml_input.test_xml_input_006)
XML-INPUT-007	CDC Configuration Parsing	Parses <config> element for cdc_en and cdc_stage settings.	Python Unit Test (xml_input.test_xml_input_007)
XML-INPUT-008	Description Support	Parses description attribute on register elements.	Python Unit Test (xml_input.test_xml_input_008)
XML-INPUT-009	Address Auto-Assignment	Assigns sequential 4-byte addresses if addr is omitted.	Python Unit Test (xml_input.test_xml_input_009)
XML-INPUT-010	Error Handling	Returns None for malformed XML or missing files, populates errors list.	Python Unit Test (xml_input.test_xml_input_010)
XML-INPUT-011	CLI Integration	Works with AxionHDL.add_source() and -s CLI flag.	Python Unit Test (xml_input.test_xml_input_011)
XML-INPUT-012	Output Equivalence	XML with same content as VHDL produces equivalent VHDL output.	Python Unit Test (xml_input.test_xml_input_012)
XML-INPUT-013	Generator Compatibility	Parses XML files generated by XMLGenerator (SPIRIT format).	Python Unit Test (xml_input.test_xml_input_013)
XML-INPUT-014	Roundtrip Integrity	Parse → Generate → Parse produces identical module dictionary.	Python Unit Test (xml_input.test_xml_input_014)
XML-INPUT-015	Unified Attribute Naming	Uses consistent attribute names between parser and generator.	Python Unit Test (xml_input.test_xml_input_015)

14. YAML Input (YAML-INPUT)

ID	Definition	Acceptance Criteria	Test Method
YAML-INPUT-001	YAML File Detection	Parser detects and loads .yaml and .yml files.	Python Unit Test (yaml_input.test_yaml_input_001)
YAML-INPUT-002	Module Name Extraction	Correctly extracts module field.	Python Unit Test (yaml_input.test_yaml_input_002)
YAML-INPUT-003	Hex Base Address Parsing	Parses base_addr as hex string.	Python Unit Test (yaml_input.test_yaml_input_003)
YAML-INPUT-004	Decimal Base Address Parsing	Parses base_addr as decimal integer.	Python Unit Test (yaml_input.test_yaml_input_004)
YAML-INPUT-005	Register List Parsing	Parses registers array with name, addr, access, width.	Python Unit Test (yaml_input.test_yaml_input_005)
YAML-INPUT-006	Access Mode Support	Handles RO, RW, WO (case-insensitive).	Python Unit Test (yaml_input.test_yaml_input_006)
YAML-INPUT-007	Strobe Signal Parsing	Parses r_strobe and w_strobe boolean flags.	Python Unit Test (yaml_input.test_yaml_input_007)
YAML-INPUT-008	CDC Configuration Parsing	Parses config.cdc_en and config.cdc_stage.	Python Unit Test (yaml_input.test_yaml_input_008)
YAML-INPUT-009	Description Field	Parses register description string.	Python Unit Test (yaml_input.test_yaml_input_009)
YAML-INPUT-010	Auto Address Assignment	Assigns sequential 4-byte addresses when addr omitted.	Python Unit Test (yaml_input.test_yaml_input_010)
YAML-INPUT-011	Invalid YAML Handling	Returns None for malformed YAML syntax.	Python Unit Test (yaml_input.test_yaml_input_011)
YAML-INPUT-012	Missing Module Name	Returns None when module field is absent.	Python Unit Test (yaml_input.test_yaml_input_012)
YAML-INPUT-013	Packed Register Parsing	Parses reg_name and bit_offset for subregister fields.	Python Unit Test (yaml_input.test_yaml_input_013)
YAML-INPUT-014	Default Value Parsing	Parses default as hex string or decimal integer.	Python Unit Test (yaml_input.test_yaml_input_014)
YAML-INPUT-015	Wide Signal Width Storage	Stores width > 32 correctly in the register dict.	Python Unit Test (yaml_input.test_yaml_input_015)
YAML-INPUT-016	signal_type Format Compatibility	The signal_type field produced by YAMLInputParser must be parseable by downstream generators (CHeaderGenerator, DocGenerator) to extract the correct bit width for all register widths (1, sub-32, 32, >32).	Python Unit Test (yaml_input.test_yaml_input_016)

15. SystemVerilog Generation (SV-GEN)

ID	Definition	Acceptance Criteria	Test Method
SV-GEN-001	Valid SystemVerilog Output	Generates syntactically correct .sv files compilable by Verilator/Vivado.	Syntax Test (test_sv_syntax)
SV-GEN-002	Reset Value Support	Registers initialize to default value defined in source (or 0 if undefined) upon reset.	SystemVerilog Test (test_sv_db_001)
SV-GEN-003	Wide Register Access	Registers >32 bits are mapped to multiple 32-bit addresses for full access.	SystemVerilog Test (test_sv_wide_001)
SV-GEN-004	Native Struct Support	Packed registers are generated as struct packed types for bitfield access.	SystemVerilog Test (test_sv_struct_001)
SV-GEN-005	Functional Verification	Generated modules support signal driving/sampling in Cocotb simulation.	Cocotb Test (test_sv_cocotb)
SV-GEN-006	Lint Compliance	Generated code passes verilator --lint-only -Wall with zero errors.	Lint Test (test_sv_lint)
SV-GEN-007	Equivalence with VHDL	SystemVerilog behavior (address map, reset, strobe) matches VHDL implementation.	Equivalence Test (test_sv_equiv)
SV-GEN-008	Bare Annotation Support	A bare // @axion annotation with no attributes is recognized and defaults to RW access, auto-assigned address, no strobes.	SystemVerilog Test (test_sv_axion_033, test_sv_axion_034)
SV-GEN-009	Address Conflict Recovery	When two signals are manually assigned the same address, the conflicting register is reassigned to the next available address instead of being dropped. A warning is recorded in parsing_errors.	SystemVerilog Test (test_sv_axion_027)

16. Enumerated Values Requirements

ID	Definition	Acceptance Criteria	Test Method
ENUM-001	BitField Data Model	BitField dataclass includes optional enum_values: Dict[int, str] field.	Python Unit Test (test_enum_001_bitfield_model)
ENUM-002	VHDL Annotation Parsing	ENUM= attribute in @axion comment is parsed to Dict[int, str].	Python Unit Test (test_enum_002_vhdl_annotation_parse)
ENUM-003	SV Annotation Parsing	ENUM= attribute in // @axion comment is parsed to Dict[int, str].	Python Unit Test (test_enum_003_sv_annotation_parse)
ENUM-004	YAML Field Enum	YAML field enum_values dict (int or string keys) is parsed to Dict[int, str].	Python Unit Test (test_enum_004_yaml_field_enum)
ENUM-005	JSON Field Enum	JSON field enum_values dict (string keys) is parsed to Dict[int, str].	Python Unit Test (test_enum_005_json_field_enum)
ENUM-006	TOML Field Enum	TOML field enum_values dict (string keys) is parsed to Dict[int, str].	Python Unit Test (test_enum_006_toml_field_enum)
ENUM-007	XML Flat Enum Attribute	Flat XML enum attribute is parsed via parse_enum_values().	Python Unit Test (test_enum_007_xml_flat_enum_attr)
ENUM-008	XML Nested Enum Elements	<enum_value value="..." name="..."/> children within <field> are parsed to enum dict.	Python Unit Test (test_enum_008_xml_nested_enum_elements)
ENUM-009	XML SPIRIT Enum	spirit:enumeratedValues/spirit:enumeratedValue elements are parsed to enum dict.	Python Unit Test (test_enum_009_xml_spirit_enum)
ENUM-010	Markdown/HTML Enum Column	Doc generator adds “Enum Values” column to packed register field table when any field has enum_values.	Python Unit Test (test_enum_010_markdown_enum_column)
ENUM-011	C Header Enum Macros	C header generator emits #define MODULE_REG_FIELD_NAME 0xVAL for each enum value.	Python Unit Test (test_enum_011_c_header_macros)
ENUM-012	YAML Export Round-Trip	YAML generator includes enum_values with string keys; re-parsed result matches original.	Python Unit Test (test_enum_012_yaml_export_roundtrip)
ENUM-013	JSON Export Round-Trip	JSON generator includes enum_values with string keys; re-parsed result matches original.	Python Unit Test (test_enum_013_json_export_roundtrip)
ENUM-014	XML SPIRIT Export	XML generator emits <spirit:enumeratedValues> block for fields with enum_values.	Python Unit Test (test_enum_014_xml_spirit_export)
ENUM-015	VHDL Comment Annotation	VHDL generator appends -- NAME=VALUE comment for fields with enum_values.	Python Unit Test (test_enum_015_vhdl_comment_only)
ENUM-016	SV Comment Annotation	SV generator appends // NAME=VALUE comment for signals with enum_values.	Python Unit Test (test_enum_016_sv_comment_only)
ENUM-018	No-Enum Regression	Modules without enum_values generate identical output to pre-feature baseline.	Python Unit Test (test_enum_018_no_enum_regression)
ENUM-019	Numeric Notations	Enum values expressed as decimal, hex (0x), and binary (0b) in source are all parsed correctly.	Python Unit Test (test_enum_019_numeric_notations)
ENUM-020	VHDL Pkg Constants	generate_vhdl_pkg() produces a .vhd package file with constant C_REG_FIELD_NAME for each enum value.	Python Unit Test (test_enum_020_vhdl_pkg_constants)
ENUM-021	SV Pkg Typedef	generate_sv_pkg() produces a .sv package file with typedef enum logic for each field.	Python Unit Test (test_enum_021_sv_pkg_typedef)
ENUM-022	Value Overflow Validation	add_field() raises ValueError when an enum value exceeds 2**width - 1; numeric notation length does not affect the check.	Python Unit Test (test_enum_022_value_overflow_validation)
ENUM-023	One-Bit Field	1-bit fields with {0: 'INACTIVE', 1: 'ACTIVE'} enum produce correct VHDL std_logic constants and SV typedef enum logic.	Python Unit Test (test_enum_023_one_bit_field)
ENUM-024	Rule Checker Overflow	RuleChecker.check_enum_value_overflow() reports an error for each enum value exceeding field width.	Python Unit Test (test_enum_024_rule_check_reports_overflow)
ENUM-025	Rule Checker Standalone Overflow	RuleChecker.check_enum_value_overflow() detects overflow in standalone (non-packed) registers with enum_values.	Python Unit Test (test_enum_025_rule_checker_standalone_overflow)
ENUM-026	VHDL Standalone Overflow E2E	A VHDL annotation with an overflowing enum value on a standalone signal triggers a rule-check error in the full parse pipeline.	Python Unit Test (test_enum_026_vhdl_standalone_overflow_e2e)
ENUM-027	SV Standalone Overflow E2E	An SV annotation with an overflowing enum value on a standalone signal triggers a rule-check error in the full parse pipeline.	Python Unit Test (test_enum_027_sv_standalone_overflow_e2e)
ENUM-028	All Overflows Reported	add_field() raises ValueError naming every overflowing enum value in a single message, not just the first.	Python Unit Test (test_enum_028_all_overflows_reported)
ENUM-029	Negative Value Rejected (BitField)	add_field() raises ValueError when an enum value is negative.	Python Unit Test (test_enum_029_negative_value_bitfield)
ENUM-030	Negative Value Rejected (RuleChecker)	RuleChecker.check_enum_value_overflow() reports an error for a negative enum value.	Python Unit Test (test_enum_030_negative_value_rule_checker)
ENUM-031	YAML Field Invalid Enum Key	YAML parser records a parsing error when a field-level enum key cannot be parsed as an integer.	Python Unit Test (test_enum_031_yaml_field_invalid_enum_key)
ENUM-032	YAML Standalone Invalid Enum Key	YAML parser records a parsing error when a standalone-register enum key cannot be parsed as an integer.	Python Unit Test (test_enum_032_yaml_standalone_invalid_enum_key)
ENUM-033	VHDL Pkg Identifier Sanitization	generate_vhdl_pkg() replaces non-alphanumeric characters in constant names with _, collapses adjacent underscores, and strips leading/trailing underscores.	Python Unit Test (test_enum_033_vhdl_pkg_identifier_sanitization)
ENUM-034	SV Pkg Identifier Sanitization	generate_sv_pkg() replaces non-alphanumeric characters in typedef/member names with _.	Python Unit Test (test_enum_034_sv_pkg_identifier_sanitization)
ENUM-035	C Header Identifier Sanitization	C header generator sanitizes enum labels to valid C identifiers in #define macros.	Python Unit Test (test_enum_035_c_header_identifier_sanitization)
ENUM-036	VHDL Pkg Returns None (No Enum)	generate_vhdl_pkg() returns None when the module has no fields with enum_values.	Python Unit Test (test_enum_036_vhdl_pkg_returns_none_no_enum)
ENUM-037	SV Pkg Returns None (No Enum)	generate_sv_pkg() returns None when the module has no fields with enum_values.	Python Unit Test (test_enum_037_sv_pkg_returns_none_no_enum)
ENUM-038	VHDL Port Comment No Double Dash	VHDL generator enum port comment uses parentheses format rather than embedding -- which would create invalid VHDL.	Python Unit Test (test_enum_038_vhdl_port_comment_no_double_dash)
ENUM-039	generate_module Co-generates Pkg	generate_module() automatically produces _regs_pkg.vhd alongside the register module when enum fields are present.	Python Unit Test (test_enum_039_generate_module_cogenerates_pkg)
ENUM-040	XML Simple Invalid Enum Value Reported	XML parser records an error when a simple-format <enum_value> has a non-integer value attribute instead of silently dropping it.	Python Unit Test (test_enum_040_xml_simple_invalid_enum_value_recorded)
ENUM-041	XML SPIRIT Invalid Enum Value Reported	XML parser records an error when a SPIRIT <spirit:value> element contains a non-integer string instead of silently dropping it.	Python Unit Test (test_enum_041_xml_spirit_invalid_enum_value_recorded)
ENUM-042	VHDL Identifier Adjacent Underscores	_sanitize_vhdl_identifier() collapses adjacent underscores to one, strips leading and trailing underscores, and prepends v_ when the result starts with a digit.	Python Unit Test (test_enum_042_vhdl_identifier_no_adjacent_underscores)

---

Typed AXI Ports (AXION-TYPES)

Covers optional generation of typed t_axi_lite_m2s / t_axi_lite_s2m record ports (VHDL) and struct ports (SystemVerilog) from axion_common_pkg, instead of the default flat individual signals.

ID	Definition	Acceptance Criteria	Test Method
AXION-TYPES-001	YAML Config Parsing	use_axion_types: true in a YAML config: block sets module_data['use_axion_types'] = True; absence or false sets False.	Python Unit Test (test_axion_types_001_yaml_config_parsing)
AXION-TYPES-002	TOML Config Parsing	use_axion_types = true in a TOML [config] table sets module_data['use_axion_types'] = True.	Python Unit Test (test_axion_types_002_toml_config_parsing)
AXION-TYPES-003	XML Config Parsing	use_axion_types="true" attribute on the <config> element sets module_data['use_axion_types'] = True.	Python Unit Test (test_axion_types_003_xml_config_parsing)
AXION-TYPES-004	JSON Config Parsing	"use_axion_types": true in a JSON config object (passed through YAML parser) sets module_data['use_axion_types'] = True.	Python Unit Test (test_axion_types_004_json_config_parsing)
AXION-TYPES-005	Default Disabled	When use_axion_types is absent from all config blocks, module_data['use_axion_types'] defaults to False.	Python Unit Test (test_axion_types_005_default_disabled)
AXION-TYPES-006	CLI Flag Override	--use-axion-types CLI flag sets use_axion_types = True on every analyzed module, overriding any per-module config value.	Python Unit Test (test_axion_types_006_cli_flag_override)
AXION-TYPES-007	VHDL Library Clause	When use_axion_types is enabled, generated VHDL includes use work.axion_common_pkg.all; in the library/use clause section.	Python Unit Test (test_axion_types_007_vhdl_library_clause)
AXION-TYPES-008	VHDL Entity Typed Ports	When use_axion_types is enabled, the VHDL entity port list contains axi_m2s : in t_axi_lite_m2s and axi_s2m : out t_axi_lite_s2m instead of the 19 flat individual AXI signals.	Python Unit Test (test_axion_types_008_vhdl_entity_typed_ports)
AXION-TYPES-009	VHDL No Flat AXI Ports	When use_axion_types is enabled, no flat AXI port names (axi_awaddr, axi_wdata, etc.) appear in the entity port list.	Python Unit Test (test_axion_types_009_vhdl_no_flat_axi_ports)
AXION-TYPES-010	VHDL Intermediate Signal Declarations	When use_axion_types is enabled, the architecture declaration region contains signal axi_awaddr, signal axi_wdata, and all other M2S and S2M intermediate signal declarations.	Python Unit Test (test_axion_types_010_vhdl_intermediate_signals)
AXION-TYPES-011	VHDL M2S Unpack Assignments	When use_axion_types is enabled, the architecture body contains concurrent signal assignments unpacking every axi_m2s record field to the corresponding intermediate signal (e.g. axi_awaddr <= axi_m2s.awaddr).	Python Unit Test (test_axion_types_011_vhdl_m2s_unpack)
AXION-TYPES-012	VHDL S2M Pack Assignments	When use_axion_types is enabled, the architecture body contains concurrent signal assignments packing every intermediate signal into the corresponding axi_s2m record field (e.g. axi_s2m.awready <= axi_awready).	Python Unit Test (test_axion_types_012_vhdl_s2m_pack)
AXION-TYPES-013	VHDL Default Unchanged	When use_axion_types is False, generated VHDL output is identical to the pre-feature baseline (flat individual AXI ports, no axion_common_pkg clause).	Python Unit Test (test_axion_types_013_vhdl_default_unchanged)
AXION-TYPES-014	SV Package Import	When use_axion_types is enabled, the generated SystemVerilog file includes import axion_common_pkg::*; before the module declaration.	Python Unit Test (test_axion_types_014_sv_package_import)
AXION-TYPES-015	SV Module Typed Ports	When use_axion_types is enabled, the SystemVerilog module port list contains input t_axi_lite_m2s axi_m2s and output t_axi_lite_s2m axi_s2m instead of the flat individual AXI signals.	Python Unit Test (test_axion_types_015_sv_module_typed_ports)
AXION-TYPES-016	SV No Flat AXI Ports	When use_axion_types is enabled, no flat AXI port names (axi_awaddr, axi_wdata, etc.) appear in the module port list.	Python Unit Test (test_axion_types_016_sv_no_flat_axi_ports)
AXION-TYPES-017	SV Intermediate Signal Declarations	When use_axion_types is enabled, the SystemVerilog module body contains logic declarations for all M2S and S2M intermediate signals.	Python Unit Test (test_axion_types_017_sv_intermediate_signals)
AXION-TYPES-018	SV M2S Unpack Assigns	When use_axion_types is enabled, the SystemVerilog module body contains assign axi_awaddr = axi_m2s.awaddr; and equivalent assigns for all M2S fields.	Python Unit Test (test_axion_types_018_sv_m2s_unpack)
AXION-TYPES-019	SV S2M Pack Assigns	When use_axion_types is enabled, the SystemVerilog module body contains assign axi_s2m.awready = axi_awready; and equivalent assigns for all S2M fields.	Python Unit Test (test_axion_types_019_sv_s2m_pack)
AXION-TYPES-020	SV Default Unchanged	When use_axion_types is False, generated SystemVerilog output is identical to the pre-feature baseline (flat individual AXI ports, no package import).	Python Unit Test (test_axion_types_020_sv_default_unchanged)
AXION-TYPES-021	Per-Module Independence	Setting use_axion_types: true on one module does not affect sibling modules parsed from the same source directory.	Python Unit Test (test_axion_types_021_per_module_independence)

18. Hierarchy File Support (HIER)

ID	Definition	Acceptance Criteria	Test Method
HIER-001	CLI --hier flag	--hier <file> argument is accepted by the CLI, the file is parsed, and hierarchy is applied before generation.	Python Unit Test (test_hier_001_cli_flag)
HIER-002	YAML hierarchy parse	A YAML-format hierarchy file is parsed correctly into a list of instance dicts.	Python Unit Test (test_hier_002_yaml_parse)
HIER-003	TOML hierarchy parse	A TOML-format hierarchy file is parsed correctly into a list of instance dicts.	Python Unit Test (test_hier_003_toml_parse)
HIER-004	JSON hierarchy parse	A JSON-format hierarchy file is parsed correctly into a list of instance dicts.	Python Unit Test (test_hier_004_json_parse)
HIER-005	XML hierarchy parse	An XML-format hierarchy file is parsed correctly into a list of instance dicts.	Python Unit Test (test_hier_005_xml_parse)
HIER-006	base_addr override (single instance)	When --hier is provided, the base_addr declared inside the individual module file is ignored and replaced by the hierarchy value.	Python Unit Test (test_hier_006_base_addr_override_single)
HIER-007	Single-instance output naming	When a module appears only once in the hierarchy and no instance field is given, the output files keep the original module name (no suffix change). If an instance field is explicitly provided, the instance name is used for output naming instead.	Python Unit Test (test_hier_007_single_instance_filename)
HIER-008	Multi-instance output naming	When a module appears more than once in the hierarchy, each instance generates separate output files named after the instance field (e.g. spi_master_0_axion_reg.vhd).	Python Unit Test (test_hier_008_multi_instance_filename)
HIER-009	instance field required for duplicates	When the same module appears more than once in the hierarchy file and more than one entry omits the instance field, HierarchyParser.parse() raises ValueError. Exactly one canonical entry (without instance name) alongside named instances is allowed (see HIER-017).	Python Unit Test (test_hier_009_missing_instance_field)
HIER-010	Duplicate instance name rejected	When the same instance name appears more than once in the hierarchy file, RuleChecker.check_hierarchy() reports an error.	Python Unit Test (test_hier_010_duplicate_instance_name)
HIER-011	Address overlap detection	When two instances have overlapping address ranges, RuleChecker.check_hierarchy() reports an error naming both instances and their ranges.	Python Unit Test (test_hier_011_address_overlap)
HIER-012	Unknown module error	When a module name in the hierarchy file is not found in the analyzed sources, RuleChecker.check_hierarchy() reports an error.	Python Unit Test (test_hier_012_unknown_module_error)
HIER-013	address_map.html generation	When --hier is provided, address_map.html is written to the output directory.	Python Unit Test (test_hier_013_address_map_html_generated)
HIER-014	address_map.html table correctness	The generated address_map.html contains a table with Instance Name, Module, Base Address, End Address, and Size columns; row values match the hierarchy and module register definitions.	Python Unit Test (test_hier_014_address_map_html_content)
HIER-015	Backward compatibility	When --hier is not provided, all existing outputs are generated with the original naming and base addresses unchanged.	Python Unit Test (test_hier_015_no_hier_backward_compat)
HIER-016	Unsupported format error	HierarchyParser.parse() raises ValueError when given a file with an unsupported extension.	Python Unit Test (test_hier_016_unsupported_format)
HIER-017	Canonical entry allowed alongside named instances	When a module appears in the hierarchy with exactly one entry that has no instance field (canonical) and one or more entries that do (named instances), HierarchyParser.parse() succeeds without error.	Python Unit Test (test_hier_017_canonical_and_instances_parse)
HIER-018	Canonical entry register space generation	The canonical entry generates its own register-space output files (VHDL, SV, C header, etc.) using the original module name and the canonical base address from the hierarchy.	Python Unit Test (test_hier_018_canonical_register_space)
HIER-019	Named instance register space generation	Each named instance entry generates its own register-space output files named after the instance field and using its base address.	Python Unit Test (test_hier_019_instance_register_space)
HIER-020	HTML/MD docs show only named instances	When canonical + named instances exist for a module, generate_html() and generate_markdown() include only the named instances; the canonical entry is excluded from the documentation.	Python Unit Test (test_hier_020_docs_exclude_canonical)
HIER-021	address_map.html excludes canonical entries	address_map.html shows only named instances; canonical entries (_hide_from_docs=True) are excluded so the canonical module does not appear anywhere in the documentation.	Python Unit Test (test_hier_021_address_map_excludes_canonical)

20. Python Register Model (REG-MODEL)

ID	Definition	Acceptance Criteria	Test Method
REG-MODEL-001	FieldModel constructed correctly	name, bit_low, bit_high, width, mask, default_value match field dict	Python Unit Test (test_register_model_001_field_model_construction)
REG-MODEL-002	FieldModel.value bit masking read	Correct bits extracted from parent raw_value via mask and shift	Python Unit Test (test_register_model_002_field_value_bit_masking_read)
REG-MODEL-003	FieldModel.value setter bit masking	Only field bits updated; other register bits are preserved	Python Unit Test (test_register_model_003_field_value_setter_bit_masking)
REG-MODEL-004	RO field write raises ReadOnlyError	FieldModel.value.setter raises ReadOnlyError for RO fields	Python Unit Test (test_register_model_004_ro_field_write_raises)
REG-MODEL-005	FieldModel.enum_name lookup	Returns string from enum_values table for current value; None if no mapping	Python Unit Test (test_register_model_005_enum_name)
REG-MODEL-006	FieldModel.reset() bypasses RO	Restores default value via _force_write_field without RO check	Python Unit Test (test_register_model_006_field_reset_bypasses_ro)
REG-MODEL-010	RegisterModel construction	name, address, access_mode, default_value, width correctly set	Python Unit Test (test_register_model_010_register_construction)
REG-MODEL-011	RW/RO/WO .value read semantics	WO returns 0; RO and RW return raw_value	Python Unit Test (test_register_model_011_rw_read_returns_raw)
REG-MODEL-012	RO write() raises ReadOnlyError	write() raises ReadOnlyError for RO registers	Python Unit Test (test_register_model_012_ro_write_raises)
REG-MODEL-013	WO read() returns 0	read() returns 0 for WO registers (bus read semantics)	Python Unit Test (test_register_model_013_wo_read_returns_zero)
REG-MODEL-014	RegisterModel.reset()	_raw_value restored to default_value; no callback, no RO check	Python Unit Test (test_register_model_014_reset_restores_default)
REG-MODEL-015	Packed register fields dict	is_packed registers have fields dict with correct FieldModel entries	Python Unit Test (test_register_model_015_packed_register_fields)
REG-MODEL-016	RegisterModel attribute access	reg.fieldname returns reg.fields[‘fieldname’]	Python Unit Test (test_register_model_016_getattr_field_access)
REG-MODEL-017	RegisterModel.dump() format	Returns non-empty string containing register name and access mode	Python Unit Test (test_register_model_017_dump_contains_name_and_value)
REG-MODEL-018	Write strobe callback fires	on_write() callback triggered exactly once when write_strobe=True	Python Unit Test (test_register_model_018_write_strobe_callback_fires)
REG-MODEL-019	Write strobe callback silent	on_write() callback not triggered when write_strobe=False	Python Unit Test (test_register_model_019_write_strobe_silent_when_false)
REG-MODEL-020	Read strobe callback fires	on_read() callback triggered when read_strobe=True and read() called	Python Unit Test (test_register_model_020_read_strobe_callback_fires)
REG-MODEL-021	Callback argument correctness	Callback receives (register_name: str, value: int) with correct values	Python Unit Test (test_register_model_021_callback_arguments)
REG-MODEL-022	raw_value WO bypass	raw_value always returns _raw_value regardless of WO access mode	Python Unit Test (test_register_model_022_raw_value_wo_bypass)
REG-MODEL-030	RegisterSpaceModel construction	from_module_dict() loads all registers; name and base_address correct	Python Unit Test (test_register_model_030_from_module_dict_loads_all)
REG-MODEL-031	Bus read by address	space.read(addr) returns register value at absolute address	Python Unit Test (test_register_model_031_bus_read_returns_value)
REG-MODEL-032	Bus write by address	space.write(addr, val) updates register raw value	Python Unit Test (test_register_model_032_bus_write_updates_register)
REG-MODEL-033	RO bus write raises	space.write() to RO register address raises ReadOnlyError	Python Unit Test (test_register_model_033_ro_bus_write_raises)
REG-MODEL-034	Unknown address read raises	space.read() at unregistered address raises AddressError	Python Unit Test (test_register_model_034_unknown_address_read_raises)
REG-MODEL-035	Unknown address write raises	space.write() at unregistered address raises AddressError	Python Unit Test (test_register_model_035_unknown_address_write_raises)
REG-MODEL-036	Space reset restores defaults	space.reset() restores all registers to their default_value	Python Unit Test (test_register_model_036_space_reset_restores_defaults)
REG-MODEL-037	Space attribute access	space.regname returns correct RegisterModel instance	Python Unit Test (test_register_model_037_space_attribute_access)
REG-MODEL-038	Field chain access	space.status.fields[‘ready’] returns correct FieldModel	Python Unit Test (test_register_model_038_field_chain_access)
REG-MODEL-039	Space on_write() callback	space.on_write(name, cb) attaches callback; fires on next write	Python Unit Test (test_register_model_039_space_on_write_attaches_callback)
REG-MODEL-040	Space dump output	dump() returns multi-line string covering header and all registers	Python Unit Test (test_register_model_040_space_dump_covers_all_registers)
REG-MODEL-041	Space registers property	registers property returns Dict[str, RegisterModel]	Python Unit Test (test_register_model_041_space_registers_property)
REG-MODEL-042	Space iteration in address order	Iterating space yields RegisterModels sorted by address	Python Unit Test (test_register_model_042_space_iteration_address_order)
REG-MODEL-050	get_model() before analyze raises	RuntimeError raised if analyze() not called before get_model()	Python Unit Test (test_register_model_050_get_model_before_analyze_raises)
REG-MODEL-051	get_model() unknown name raises	KeyError raised for module name not found in analyzed_modules	Python Unit Test (test_register_model_051_get_model_unknown_name_raises)
REG-MODEL-052	get_model() success	Returns RegisterSpaceModel with matching name after analyze()	Python Unit Test (test_register_model_052_get_model_returns_space)
REG-MODEL-053	get_models() all modules	Returns dict mapping all module names to RegisterSpaceModel instances	Python Unit Test (test_register_model_053_get_models_returns_dict)
REG-MODEL-054	YAML round-trip	YAML → analyze → get_model → write → read returns correct value	Python Unit Test (test_register_model_054_yaml_round_trip)
REG-MODEL-055	get_model() entity_name fallback	Finds module when ‘entity_name’ key used instead of ‘name’	Python Unit Test (test_register_model_055_get_model_by_entity_name)
REG-MODEL-060	PythonGenerator creates file	generate() creates *_regs.py in output directory	Python Unit Test (test_register_model_060_generator_creates_file)
REG-MODEL-061	Generated file importable	Generated *_regs.py imports without error via importlib	Python Unit Test (test_register_model_061_generated_file_importable)
REG-MODEL-062	Generated symbol is RegisterSpaceModel	Uppercase symbol in generated file is a RegisterSpaceModel instance	Python Unit Test (test_register_model_062_generated_module_symbol)
REG-MODEL-063	Generated model functional	Generated model supports write/read returning correct values	Python Unit Test (test_register_model_063_generated_model_functional)
REG-MODEL-064	generate_python() API	AxionHDL.generate_python() produces *_regs.py files for all modules	Python Unit Test (test_register_model_064_cli_python_flag)
REG-MODEL-065	Packed register in generated file	Generated model correctly exposes packed registers and their fields	Python Unit Test (test_register_model_065_packed_register_generation)