FPGA-Core/Tutorial/phase-00-architecture-contract/phase-00-01-systemverilog-package.md

Phase 0.1 - SystemVerilog Package

Context

The package is the shared type layer for the project. It prevents every module from inventing its own encodings and signal names.

Goals

• Define enums for ALU operations, branch types, memory sizes, and instruction classes.
• Define structs for stage outputs and memory request/response payloads.
• Make later extension possible without rewriting every module boundary.

New Concepts

• Packed struct: a struct with a defined bit layout, suitable for wires and registers.
• Typedef: named type alias used to make RTL readable.
• Import: SystemVerilog mechanism for using package definitions in modules.
• Encoding: the bit pattern used for enum values in synthesized hardware.

How To Think About It

The package is not a dumping ground. It should contain stable contracts and shared definitions. If a signal is private to one module, keep it private.

Learning Tasks

• List every planned stage boundary and define what information must cross it.
• Separate architectural information, such as register addresses, from local control.
• Decide naming conventions before writing dependent modules.

Pitfalls

• Relying on implicit enum widths and later discovering mismatched synthesis behavior.
• Putting handshake ready signals inside one-way payload structs.
• Adding fields "just in case" without knowing who drives or consumes them.

Tooling And Testing

• Compile the package alone and then with one tiny importing module.
• Inspect elaboration messages; type errors here are usually design-contract errors.
• Keep comments on fields short but precise about direction and ownership.

References

• SystemVerilog packages and typedefs: https://www.chipverify.com/systemverilog/systemverilog-package
• LowRISC SystemVerilog style: https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md
• RISC-V unprivileged ISA: https://riscv.org/technical/specifications/