# 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://verificationguide.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/