imple
b008b37d49
Add a Tutorial tree that mirrors the roadmap from Phase 0 through Linux bring-up. Each phase and subphase gets a short learning note with consistent sections for context, goals, new concepts, mental model, learning tasks, pitfalls, tooling, testing, and references. The tutorial material is intentionally explanatory rather than implementation code. It gives a systems-oriented learner enough FPGA, SystemVerilog, RISC-V, firmware, and Linux bring-up context to approach each roadmap phase without turning the notes into copy-paste RTL.
50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# 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/
|
|
|