How to Write an RTL Design Specification for Better Verilog

A lot of RTL bugs begin before anyone writes Verilog.
The problem is often not syntax or a badly written state machine. It is that two engineers can read the same requirement and build two different circuits from it.
An RTL design specification is the contract that removes that ambiguity. It defines what a hardware block must do before implementation: its purpose, interface, clocking, reset behavior, functional rules, timing, edge cases, priority rules, implementation constraints, and verification expectations.
Consider a requirement as simple as:
Create a FIFO.
That sounds clear until implementation starts.
How wide is the data? How deep is the FIFO? Is reset synchronous or asynchronous? What happens if you read while empty? Should a write while full be ignored? What happens when read and write are asserted together? Is rd_data combinational or registered?
Every one of those choices changes the resulting RTL.
A good specification makes those decisions before they become bugs.
What Is an RTL Design Specification?
An RTL design specification describes the required behavior and interface of a digital hardware block before that behavior is implemented in Verilog, SystemVerilog, or VHDL.
At RTL, time matters. Clock edges matter. Registers matter. Signal widths matter. Reset behavior, latency, and boundary conditions all affect the circuit that will eventually be synthesized.
A useful specification therefore defines the observable contract of the hardware.
| Area | Question the specification should answer |
|---|---|
| Purpose | What does this block do? |
| Interface | What are its inputs, outputs, widths, and parameters? |
| Clocking | Which clock controls the block? |
| Reset | What type of reset is used, and what state does it produce? |
| Behavior | What happens during normal operation? |
| Timing | When are inputs sampled and outputs updated? |
| Boundaries | What happens at full, empty, overflow, underflow, minimum, maximum, or invalid conditions? |
| Priority | If several conditions occur together, which one wins? |
| Constraints | Are outputs registered? Are latches forbidden? Is the block single-clock? |
| Verification | Which behaviors must the testbench explicitly check? |
The document does not need to be long. It needs to be precise where the hardware cannot afford interpretation.
Where an RTL Design Specification Fits
Hardware teams use different names for specification documents, so the exact boundaries vary from company to company.
A typical flow looks roughly like this:
System requirement → block or IP specification → microarchitecture → RTL implementation → verification
A system requirement describes what the larger product needs.
A block or IP specification defines what one hardware block must expose and how it must behave.
Microarchitecture describes how that behavior will be implemented internally: pipelines, state machines, FIFOs, memories, arbitration logic, and other structures.
RTL then expresses that architecture in synthesizable code.
For small modules, the block requirements and microarchitecture may live in the same short document. The important point is knowing which decisions are already defined and which are still open.
Start With What the Block Is Supposed to Do
The first sentence should establish the purpose of the module.
A single-clock synchronous FIFO that stores data between a producer and consumer.
That already communicates more than “make a FIFO.” It also makes clear that this is not an asynchronous FIFO requiring clock-domain-crossing logic.
For another design:
A four-requester round-robin arbiter that grants at most one requester per clock cycle.
Or:
A UART transmitter that sends 8-bit words using a configurable baud rate, optional even parity, and one stop bit.
Keep the purpose short. The rest of the specification defines exactly how the block behaves.
Define the Interface Before the Behavior
Once the purpose is clear, define what connects to the module.
| Signal | Direction | Width | Meaning |
|---|---|---|---|
clk |
Input | 1 | Module clock |
rst_n |
Input | 1 | Active-low synchronous reset |
wr_en |
Input | 1 | Request to write one entry |
wr_data |
Input | DATA_WIDTH |
Data to write |
rd_en |
Input | 1 | Request to read one entry |
rd_data |
Output | DATA_WIDTH |
Registered data returned by a valid read |
full |
Output | 1 | No additional write can currently be accepted |
empty |
Output | 1 | No valid entry is currently available to read |
count |
Output | Enough for 0..DEPTH | Number of valid entries |
The parameters might be:
DATA_WIDTH = 32
DEPTH = 16
An interface derived from that specification could begin like this:
module sync_fifo #(
parameter DATA_WIDTH = 32,
parameter DEPTH = 16,
parameter COUNT_WIDTH = 5
)(
input wire clk,
input wire rst_n,
input wire wr_en,
input wire [DATA_WIDTH-1:0] wr_data,
input wire rd_en,
output reg [DATA_WIDTH-1:0] rd_data,
output reg full,
output reg empty,
output reg [COUNT_WIDTH-1:0] count
);
The specification determines the interface. The code simply expresses it.
Be Explicit About Clock and Reset
“Reset the FIFO” is not a sufficient requirement.
The specification should define whether reset is synchronous or asynchronous, its polarity, priority, and the externally visible state after reset.
The FIFO uses a single rising-edge clock. Reset is synchronous and active low. Whenrst_nis sampled low on a rising edge, the read pointer, write pointer, occupancy count, and status state return to their initial values. After reset,count = 0,empty = 1,full = 0, andrd_data = 0.
Reset strategy is also more than a coding-style choice. AMD's UltraFast Design Methodology guidance discusses how reset architecture can affect FPGA resource usage, performance, area, and power.
Read AMD UG949 guidance on resets .
Specify Timing in Clock Cycles
One of the most common specification mistakes is defining what an output should be without defining when it should appear.
Consider:
When rd_en is asserted, output the next FIFO entry.
That still leaves an important ambiguity.
Should rd_data change combinationally during the same cycle, or should it update after the next rising edge?
Those are different interfaces.
A better requirement is:
rd_datais registered. Whenrd_en = 1and the FIFO is not empty, the oldest stored entry is captured on the rising edge andrd_dataupdates immediately after that edge. The value remains unchanged until another valid read or reset updates it.
The same principle applies to almost every synchronous module.
Instead of:
Raise done when processing finishes.
write:
Assert done for one clock cycle immediately after the rising edge that completes the final operation.
Cycle-level language removes assumptions.
Define Boundary Conditions Before They Become Bugs
Normal operation is usually the easiest part of a hardware block.
The more interesting bugs appear at the boundaries.
For a FIFO, the specification should explicitly define what happens during full, empty, and simultaneous read/write conditions.
- A write while
full = 1is ignored. - A read while
empty = 1is ignored andrd_dataretains its previous value. - When read and write are both valid in a normal state, both operations happen on the same clock edge and occupancy stays unchanged.
- When the FIFO is empty and both requests are asserted, only the write is accepted. There is no same-cycle bypass.
- When the FIFO is full and both requests are asserted, only the read is accepted. There is no same-cycle replacement write.
Those are not the only possible FIFO semantics.
Another design might deliberately support first-word fall-through, bypass behavior, or simultaneous replacement at full.
The important thing is that the specification chooses.
Define Priority When Multiple Conditions Happen Together
Hardware evaluates many signals concurrently, so specifications need to define priority.
If the eventual RTL contains:
if (!rst_n)
...
else if (clear)
...
else if (enable)
...
then the code has defined a priority order.
That priority should exist in the specification first:
Reset has highest priority. Clear has priority over enable. If clear and enable are asserted on the same rising edge, the state is cleared and no normal update occurs.
Describe Requirements Before Implementation Choices
A specification should primarily describe what the module must do.
For example:
The FIFO must preserve write order.
is a behavioral requirement.
By contrast:
Use this exact pointer implementation.
is normally an implementation choice.
A useful rule is:
Behavior first. Constraints second.
A Vague FIFO Specification vs. an Implementation-Ready One
Consider:
Build a FIFO in Verilog.
Almost every important decision is still undefined.
A stronger RTL design specification looks like this:
Create a synthesizable single-clock synchronous FIFO.
Parameters:
DATA_WIDTH = 32 by default.
DEPTH = 16 by default.
DEPTH must be a power of two.
Interface:
clk
rst_n
wr_en
wr_data[DATA_WIDTH-1:0]
rd_en
rd_data[DATA_WIDTH-1:0]
full
empty
count
Clock and reset:
All state changes occur on the rising edge of clk.
Use synchronous active-low reset.
After reset:
count = 0
empty = 1
full = 0
rd_data = 0
Write behavior:
When wr_en = 1 and full = 0, store wr_data and advance
the write pointer.
When full = 1, ignore the write request.
Read behavior:
When rd_en = 1 and empty = 0, read the oldest stored
entry and advance the read pointer.
rd_data is registered and updates after the accepting
clock edge.
When empty = 1, ignore the read request and retain
the previous rd_data value.
Simultaneous operation:
When wr_en and rd_en are both asserted and the FIFO is
neither full nor empty, perform both operations during
the same clock edge. Occupancy remains unchanged.
When empty and both requests are asserted, accept only
the write. Do not bypass wr_data to rd_data.
When full and both requests are asserted, accept only
the read. Do not replace the removed entry with the
requested write in the same cycle.
Flags and count:
count is a registered output representing the number
of valid stored entries.
empty and full are registered outputs updated from the
next occupancy state.
empty = 1 when the resulting count is 0.
full = 1 when the resulting count is DEPTH.
Constraints:
One clock domain.
No inferred latches.
Synthesizable RTL only.
Verification:
Check reset state.
Check FIFO ordering.
Check normal writes and reads.
Check full behavior.
Check empty behavior.
Check simultaneous read/write.
Check simultaneous operations while empty and full.
Check occupancy count.
Check transitions into and out of full and empty states.
This specification is longer than “build a FIFO,” but almost every line determines either the RTL or the verification environment.
Turn Each Requirement Into a Verification Question
A useful test for specification quality is:
Could another engineer write the testbench from this document without guessing?
| Requirement | Verification question |
|---|---|
| Reset produces a known empty state | After reset, are empty=1, full=0, count=0, and rd_data=0? |
| FIFO preserves order | Do reads return values in exactly the order they were accepted? |
| Writes are blocked while full | Does an attempted full write leave the FIFO unchanged? |
| Reads are blocked while empty | Does an attempted empty read leave state and rd_data unchanged? |
| Read output is registered | Does rd_data update only after the accepting clock edge? |
| Normal simultaneous read/write | Do both operations occur while occupancy remains unchanged? |
| Request at empty | Is only the write accepted, with no bypass? |
| Request at full | Is only the read accepted? |
| Count tracks valid entries | Does count match all accepted operations? |
For a practical example of turning requirements into automatic checks, see our self-checking testbench in Verilog guide.
RTL Design Specification Review Checklist
| Check | Question |
|---|---|
| Purpose | Could another engineer explain the block after reading one paragraph? |
| Interface | Are all ports, directions, widths, and parameters defined? |
| Clocking | Is every clock domain and active edge explicit? |
| Reset | Are reset type, polarity, priority, and post-reset values defined? |
| Timing | Is the latency of every important output unambiguous? |
| Edge cases | Are boundary and invalid conditions defined? |
| Simultaneous events | Is behavior defined when several requests occur together? |
| Priority | Are competing controls given an explicit priority? |
| Constraints | Are genuinely required architecture or synthesis constraints stated? |
| Verification | Can every important requirement become an objective test? |
If several answers are “no,” the RTL author will probably have to invent behavior during implementation.
Include Arithmetic Rules When Numbers Matter
Arithmetic blocks introduce another class of ambiguity.
Suppose the requirement says:
Add two signed values.
You still need to define widths and overflow behavior.
A clearer requirement is:
Accept two signed 16-bit two's-complement operands. Produce a signed 17-bit result so the complete addition result is preserved. Sample the operands when valid_in = 1 on a rising edge and present the registered result one cycle later.
For arithmetic RTL, width and signedness are part of functionality.
Include Parameters Only When They Are Real Requirements
Parameterized RTL is useful, but not every constant needs to become configurable.
A parameter is most useful when users of the block are genuinely expected to change it.
For a FIFO, DATA_WIDTH and DEPTH make sense. For a UART, clock frequency or baud-rate configuration may make sense.
The specification should distinguish between configuration the user needs and implementation details the module can choose internally.
State Constraints That Actually Matter
Some requirements are not immediately visible in a functional waveform but still matter to implementation.
- Single clock domain
- Registered outputs
- No inferred latches
- Specific memory-resource inference
- Target FPGA family
- Target operating frequency
Include these when violating them would cause the implementation to be rejected.
What Not to Put in an RTL Specification
More text does not automatically mean a better specification.
Avoid repeating the same behavior in several paragraphs. Avoid pasting an entire protocol document when only a small part applies. Avoid combining unrelated blocks in one requirement. And avoid spending more time describing coding style than defining timing, interfaces, reset, or boundary behavior.
If a sentence would not change the RTL, verification plan, or acceptance criteria, ask whether it needs to be in the module specification.
A Reusable RTL Design Specification Template
MODULE
What block is being built and what problem does it solve?
PARAMETERS
Which widths, depths, timing values, or operating modes
are configurable?
INTERFACE
List every input and output, its width, direction, and meaning.
CLOCKING
Which clock domain controls the block?
Which edge is active?
RESET
Synchronous or asynchronous?
Active high or active low?
What state must exist after reset?
FUNCTIONAL BEHAVIOR
Describe normal operation in observable terms.
TIMING
When are inputs sampled?
When do outputs change?
What is the latency?
BOUNDARY CONDITIONS
What happens at minimum, maximum, empty, full, overflow,
underflow, invalid, or unsupported conditions?
SIMULTANEOUS EVENTS
What happens when multiple requests occur in the same cycle?
PRIORITY
Which controls override which other controls?
CONSTRAINTS
Registered outputs?
Single clock?
No latches?
Target device?
Resource or frequency requirements?
VERIFICATION
Which behaviors and edge cases must be explicitly checked?
What Is the Difference Between a Functional Spec and a Microarchitecture Spec?
A functional specification describes what the block must do from the outside.
A valid read returns the oldest FIFO entry.
A microarchitecture specification describes how that behavior will be implemented internally.
Use a dual-port RAM with read and write pointers and an occupancy counter.
Several microarchitectures can often satisfy the same functional contract.
Using an RTL Design Specification With a Verilog Generator
The same rules become even more useful when a specification is used as input to an RTL-generation workflow.
Compare:
Generate a FIFO.
with the implementation-ready specification above.
The detailed version leaves much less room for an incorrect assumption about reset, timing, full behavior, simultaneous operations, or verification expectations.
A good specification therefore serves two purposes:
- It gives implementation a clear target.
- It gives verification an independent description of what the design should do.
SiliCode can use a hardware specification as the starting point for RTL generation and verification workflows. The important principle is the same whether the implementation is generated or written manually: define the behavior before the code defines it.
For related workflows, see our AI Verilog generator and Verilog testbench generator guides.
A Better Specification Does Not Replace Engineering Review
A detailed specification reduces ambiguity. It does not guarantee a correct implementation.
RTL can still contain bugs. A testbench can miss an important case. The specification itself can be wrong. Functional simulation alone does not prove timing closure, clock-domain-crossing correctness, complete coverage, or production readiness.
A useful sequence is:
define the intent → implement → verify the defined behavior → synthesize and review → continue with the sign-off process appropriate to the project
Frequently Asked Questions
What should an RTL design specification include?
At minimum, define the block's purpose, interface, clocking, reset behavior, normal operation, timing or latency, boundary conditions, simultaneous-event behavior, priority rules, required constraints, and the behaviors that must be verified.
How detailed should an RTL specification be?
It should be detailed enough that another engineer can implement the block without making important behavioral decisions on your behalf. A small module may need only a few paragraphs, while a configurable controller or datapath may require much more.
Should reset behavior always be specified?
For sequential logic that uses reset, yes. Specify the reset type, polarity, priority, and required post-reset state. If a block intentionally has no reset, state that explicitly.
What is the difference between a requirement and an implementation detail?
A requirement defines externally visible behavior or a mandatory constraint. An implementation detail defines how that behavior is achieved internally. “Preserve FIFO ordering” is a requirement. “Use this exact pointer implementation” is normally an implementation choice.
What's the difference between a functional specification and a microarchitecture specification?
A functional specification describes what the hardware must do. A microarchitecture specification describes how the design will implement that behavior internally.
Should an RTL specification define what happens during illegal operations?
Yes, when those operations can occur at the interface. Define whether the request is ignored, flagged as an error, produces a defined response, or is prohibited by an explicit interface assumption.
Can a natural-language specification be used to generate Verilog?
Yes. Natural-language hardware requirements can be used as input to RTL-generation tools. Clear interface, timing, reset, edge-case, and verification requirements reduce the number of assumptions the implementation must make.
Does a detailed RTL specification guarantee correct RTL?
No. It reduces ambiguity but does not prove implementation correctness. RTL should still be reviewed, simulated, synthesized, and subjected to the verification and sign-off process appropriate to the project.
Write the Contract Before the Code
The best time to decide what reset does, when an output becomes valid, or what happens at a boundary is before those decisions are hidden inside RTL.
Define the interface. Define time. Define the edge cases. Define what must be verified.
Then implement against that contract.
Have a specification you want to try? Start free with SiliCode →