Two teams build the two sides of a new interface from the same specification. Months later the blocks meet in simulation and fail on the first transfer. The sender drops valid while it is stalled; the specification's timing diagram never showed a stall, and its prose said "the sender presents data with valid". Each team read it differently, and each reading was reasonable. The specification was the bug.
What must an interface specification contain so that two teams who never talk can build blocks that work together?
The obvious specification is a signal list, a description of what each signal means, and a few timing diagrams of typical transfers. That describes the happy path. The failures live elsewhere: stalls, back-to-back transfers, resets in the middle, errors, maximum outstanding requests, the cycle where two events coincide. A diagram shows one example; it does not say which features of the example are rules and which are accidents. Every gap is filled by each team's assumption, and the assumptions differ.
Section | What it says | Common gap |
|---|---|---|
Roles and signals | Who drives each signal, its width, its reset value, which clock | Reset values and which side drives what during reset |
Rules (numbered) | Every obligation, each one testable on the wires: "once valid is high, it stays high until valid and ready are both high" | Rules only implied by a diagram |
Allowed and forbidden freedoms | What a side may do (ready may depend on valid; responses may come in any order across IDs) and may not do | Assuming the partner will not use a freedom the spec gives it |
Transaction semantics | What each transfer means: ordering, completion, error responses | Ordering left to "obvious" |
State machines and tables | Where behaviour depends on history: link states, credit initialisation | Prose instead of an exhaustive table |
Timing diagrams | Examples, including stalls, back-to-back and errors, each labelled as an example | Diagrams read as rules |
Parameters and limits | Maximum outstanding, burst length, credit counts, timeouts | Limits a block silently assumes |
Reset, errors and corner cases | Mid-transfer reset, error paths, simultaneous events | Missing entirely |
Each rule should be a statement about the interface's signals that a checker could evaluate cycle by cycle, with a number so that reviews, assertions and bug reports can refer to it. Compare:
Weak: "The sender presents data with valid."
Strong: R3. Once vld is high, vld stays high, and data and last stay
unchanged, until the cycle in which vld and rdy are both high.
R4. vld must not depend combinationally on rdy.
R5. rdy may depend on vld.
R6. A packet ends with last; a packet has at most 8 beats.Each strong rule maps to one assertion (lesson 15.3). If you cannot write the assertion, the rule is not yet precise enough.
Implementation: how a side meets the rules (buffer sizes, pipelines) is its own business unless it is visible on the wires.
Unnecessary restrictions: every rule constrains both teams forever; forbid only what would break the other side.
Duplicated statements: say each rule once; two slightly different statements of one rule become two rules.
Specification | Practice |
|---|---|
AMBA AXI | Explicit handshake rules and channel dependency rules, stated separately from the timing examples (facts A1, A2, A21) |
PCI Express | Numbered requirements and exhaustive tables such as the ordering table (fact P28) |
Register maps | Machine-readable descriptions (IP-XACT, SystemRDL) from which RTL, documents and checks are generated (fact T13) |
The opening failure (illustrative) was fixed by adding a single numbered rule (R3 above) and an assertion for it to both teams' testbenches. A review of the rest of the specification against the question "could each statement be an assertion?" found eleven more statements that were really examples, three of which the two teams had implemented differently.
Not unless the text says so; diagrams are examples. A good specification states whether ready may come earlier, later or at the same time.
Try to write it as an assertion over the interface signals; if you cannot, it is still ambiguous.
A specification is a contract between teams who may never talk: every gap becomes a disagreement.
Write numbered rules that can each become an assertion; label diagrams as examples; state freedoms and limits.
Cover stalls, back-to-back, resets, errors and simultaneous events; leave out implementation.