hdl-module-designlisted

# HDL Module Design ## Overview A hardware module is an interface plus an implementation. Get the interface and its configuration right and the implementation stays swappable, testable, and reusable across an FPGA and an ASIC. **Core principle:** A module should declare exactly what it needs as typed configuration, validate it at build time, and be exhaustively testable in isolation. If you can't construct and test it without the rest of the SoC, the boundary is wrong. ## When to Use - Writing a new peripheral, datapath, control block, or reusable IP - A module takes a pile of bare `int`/`String`/`bool` constructor args - Configuration is validated late (at elaboration or simulation) instead of at construction - Domain logic is leaking into the CLI/generator wrapper instead of the library - Tests only exercise the top level, not the component Skip for throwaway testbench glue or a one-line wire rename. ## Design The Configuration First Hardware bugs are expensive, so push errors as early as possible: ideally a type error, otherwise a build-time assertion, never a silent miscompile. 1. **One config object per module.** Group the parameters into an immutable config type with named, typed fields. The module takes the config, not a long positional arg list. 2. **Types, not strings.** Use enums for modes, kinds, and identifiers. `BusKind.axi4` not `"axi4"`. A typo becomes a compile error instead of a wrong build. 3. **Validate at construction.** Width relationships, power