Bad specs create endless RTL thrash. A good spec is not a novel — it is a contract: what the design must do, how fast, on which pins, and how you will know it is done.
Spec quality = how clearly you can turn MUST lines into tests.
Trap: “Make it work like the competitor chip” with zero numbers. That is not a spec — it is a wish.
| Letter | Means | Spec example (I2C) |
|---|---|---|
| Specific | One behavior per line | M3: Detect ACK/NACK after each byte |
| Measurable | Numbers or observable signals | M1: Standard-mode 100 kHz SCL target |
| Achievable | Feasible at target node / clock | No “1 GHz I2C” on a 50 MHz sysclk without justification |
| Relevant | Tied to product need | Sensor read — not “add UART because cool” |
| Time-bound | Version / milestone | v1: write-only; v2: clock stretch |
| ❌ Vague (fights later) | ✅ Testable (design can implement) |
|---|---|
| “Fast I2C” | MUST meet I2C standard-mode bit timing with SCL period ≥ 10 µs |
| “Handle errors gracefully” | MUST set sticky NACK bit and deassert BUSY within 1 byte time on slave NACK |
| “Low power” | SHOULD gate clk_sys to bit engine when STAT.BUSY=0 |
| “Support all addresses” | MUST support 7-bit addressing; 10-bit is MAY for v2 |
Words like robust, seamless, and user-friendly belong in marketing slides — not in MUST lines. Replace each with a signal, timing number, or pass/fail test.
Non-negotiable. Missing it is a bug.
Strong preference; skip only with written reason.
Optional. Nice for v2.
Example: “The I2C master MUST generate START/STOP per Spec Rev 1. The UI MAY expose a debug counter.”
Requirements change — the failure mode is silent change. Good teams use:
When PM adds a feature mid-sprint, ask: “Is this a new MUST? Which acceptance test proves it?” That one question saves weeks of argument.
Before coding, a designer should answer:
A menu that says “tasty food” cannot be cooked consistently. A menu that lists ingredients, sizes, and allergens can. Specs are menus for silicon.
ACCEPTANCE TEST ID: A# TITLE: <one-line behavior> PRECONDITION: <reset state, clocks, config registers> STIMULUS: <step-by-step transactions> EXPECTED: <signals / CSR bits / timing> PASS CRITERIA: <automatable check — not "looks good"> OWNER: DV / designer MUST REF: M#
Write 5 MUST lines for an I2C master (even if rough). Example starter:
Keep this list — Module 11 will turn it into a real one-page spec.
Here is how a real (tiny) I2C master micro-spec might start — copy this style into your notes:
IP: i2c_master_v1 PURPOSE: Let software read/write I2C sensors on the board. MUST: M1. Support 7-bit addressing, standard-mode (100 kHz target) M2. Generate START, STOP, repeated-START per I2C timing rules M3. Detect ACK/NACK after every address and data byte M4. Expose BUSY and NACK sticky status bits in CSR M5. Allow software abort of a hung transfer (ABORT bit) SHOULD: S1. Support clock stretching from slave S2. Interrupt on DONE / NACK MAY: X1. Debug byte counter (v2) ACCEPTANCE: A1. Directed TB: START -> addr+W -> data -> STOP, ACK path PASS A2. Directed TB: slave NACK sets sticky NACK, clears BUSY A3. Abort during BUSY returns FSM to IDLE within 1 byte time
Worked example — clock stretch corner (SHOULD line becomes a test):
S1. SHOULD support clock stretching from slave
ACCEPTANCE A4 (stretch):
PRE: Master in byte transfer, SCL released high
STIM: Slave holds SCL low for 50 µs then releases
EXPECT: Master waits (no premature STOP); BUSY remains 1;
transfer completes after release
PASS: TB measures SCL low time; FSM does not timeout before S1 limit
“How do you know when RTL is done?” — Point to acceptance tests tied to MUST lines, not “simulation passed once.” Done = spec contract satisfied with evidence.
| Spec quality | Typical downstream cost |
|---|---|
| Clear MUST + acceptance | One RTL pass, predictable schedule |
| Vague features | 3+ RTL rewrites, blame games |
| Missing corner cases | Silicon bug + firmware workaround |
| No change control | “Surprise” features break ABI |
MUST M8: Read transaction MUST issue repeated-START after address byte (R/W=1)
MUST M9: RXDATA valid only when STAT.DONE=1 and STAT.NACK=0
ACCEPTANCE A6:
PRE: Slave model returns 0x42 on read
STIM: Write addr+W, repeated-START, addr+R, read byte, STOP
EXPECT: RXDATA=0x42, DONE=1