hdl-module-design

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-of-two requirements, address-range overlaps, legal mode combinations: assert them when the config is built, with a message that names the offending field and value. Do not defer to simulation.
4. Derive, don't duplicate. If addrWidth is a function of depth, compute it. Don't make the caller pass both and hope they agree.

// ROHD-flavored, but the shape is language-neutral.
class FifoConfig {
  final int depth;
  final int width;
  const FifoConfig({required this.depth, required this.width});

  // build-time validation, names the bad field
  void validate() {
    if (depth <= 0 || (depth & (depth - 1)) != 0) {
      throw ArgumentError('FifoConfig.depth must be a power of two, got $depth');
    }
    if (width <= 0) {
      throw ArgumentError('FifoConfig.width must be positive, got $width');
    }
  }

  int get addrWidth => depth.bitLength - 1; // derived, not passed in
}