Project specifications
The file that says what a design must do, the sections the starters use, and how the lab and its agents rely on it.
On this page
The sections a starter usesWhat each section settlesWhy the Clock section explains itselfWhen something is undecidedHow the lab uses itA specification says what the design must do. It is the reference for the code and for the test. Without it, a test can only check that the code does what the code does.
In this lab a project's specification is the file docs/DESIGN.md. Every starter comes with one.
The sections a starter uses#
This is the specification of the MAC-8 starter, shortened. Your own should answer the same questions.
# Design: 8-bit Multiply-Accumulate Unit
## Interface
| Port | Direction | Width | Meaning |
|---|---|---|---|
| `clk` | input | 1 | Clock, rising edge |
| `rst_n` | input | 1 | Reset, active low, asynchronous |
| `en` | input | 1 | Accumulate on this clock |
| `a` | input | 8, signed | First operand |
| `b` | input | 8, signed | Second operand |
| `acc` | output | 20, signed | Running sum of products |
## Intended behaviour
On every rising clock edge where `en` is high: `acc <= acc + a * b`.
When `en` is low, `acc` holds its value.
## Reset
`rst_n` low clears `acc` to 0 immediately, without waiting for a clock.
## Latency
One clock. Inputs sampled on a rising edge appear in `acc` after that edge.
## Range
One product is between -16256 and 16384. `acc` is 20 bits, so at least 32
worst-case products fit before it wraps. Wrap-around is not detected.
## Clock
One clock, `clk`, 15 ns period (66.7 MHz) for the ASIC build.What each section settles#
| Section | The question it answers |
|---|---|
| Interface | Every port: direction, width, signed or not, and what it means |
| Intended behaviour | What the block does on each clock, and what it does when idle |
| Reset | The value each stored signal takes at reset, and whether reset waits for a clock |
| Latency | How many clocks from an input to the output it affects |
| Range | How large values can get, and what happens on overflow |
| Clock | The clock period the build must meet, and why that number |
Why the Clock section explains itself#
The MAC-8 specification does not only state 15 ns. It records that at 10 ns the design met timing at the typical corner and missed it by about 2 ns at the slow corner, and that registering the inputs would allow a faster clock at the cost of one more clock of latency. That is the habit to copy: a number in a specification should say where it came from.
When something is undecided#
If a choice changes the interface or the behaviour someone else depends on, decide it before writing code. If the choice is minor, choose, and write it down as an assumption in the section it belongs to.
How the lab uses it#
Design Chat reads the specification before it answers. The timing agents treat a clock or latency stated there as a requirement. See How agents use DESIGN.md.
Something unclear or missing? Send feedbackSign in and use Feedback to tell us.