SystemVerilog that reads like one engineer wrote it.

The description is the only part of a file that survives being read out of context -- in a diff, a search result, or a model's context window. Copyright and licence state must be mechanical, not remembered, because a file that ships without it is a legal problem discovered late.

// Copyright (c) 2026 ACME Corp
// All rights reserved
//
// Description:
//   Synchronous FIFO with first-word-fall-through. Depth must be a power of
//   two. Full and empty are registered.

// fifo.sv
module fifo #(

Sources: house style, lowRISC §Basic Template (shown as a template, not stated as a rule)

A description that repeats the identifier adds a line and no information. The constraints -- power-of-two depth, one-hot input assumption, latency -- are what a reader cannot recover from the port list.

// Description:
//   Gray-code pointer synchroniser. Source and destination clocks are
//   asynchronous; the pointer must change by at most one per source clock.

// Description:
//   Gray counter module.

Sources: house style

The port list is the module's contract, and it is the one part of a module that other engineers and models read without opening the body. Direction and type are in the declaration; what the signal means, when it is valid and what it is relative to are not.

input  logic        clk_i,    // System clock
input  logic        rst_ni,   // Asynchronous reset, active-low
input  logic [7:0]  data_i,   // Payload byte, valid while valid_i is high
output logic        ready_o   // Sink can accept a byte this cycle

input  logic        clk_i,
input  logic        rst_ni,
input  logic [7:0]  data_i,
output logic        ready_o

Sources: house style

A declaration is where a signal's purpose can be stated once instead of re-derived at every use. Enum members are exempt because their meaning belongs on the FSM case arm that acts on them, which is where lowRISC puts it -- commenting both places guarantees the two drift apart.

localparam int unsigned DepthW = $clog2(Depth);  // Bits needed to index the RAM
logic [DepthW-1:0] wptr_q, wptr_d;               // Write pointer, binary

localparam int unsigned DepthW = $clog2(Depth);
logic [DepthW-1:0] wptr_q, wptr_d;

Sources: house style

Orientation without structure: the comment scrolls with the code and folds with it, so a reader skimming a collapsed module still sees what each block is for. Framed banner comments would do the same job but break native editor folding and rot when code moves.

// Advance the write pointer on an accepted write.
always_ff @(posedge clk_i or negedge rst_ni) begin

always_ff @(posedge clk_i or negedge rst_ni) begin

Sources: house style

The instance name says which module; the comment says why this design needs it. A reader tracing a signal through a hierarchy needs the second, and it is the thing the code cannot state.

// Two-flop synchroniser for the request from the slow domain.
prim_flop_2sync #(.Width(1)) u_req_sync (

prim_flop_2sync #(.Width(1)) u_req_sync (

Sources: house style

Quoting lowRISC: "A comment on its own line describes the code that follows. A comment on a line with code describes that line of code." Consistent placement is what lets a tool insert and a reader trust trailing comments at all.

// Hold the request until the far side acknowledges.
assign req_d = req_q & ~ack_i;  // Cleared by the synchronised ack

assign req_d = req_q & ~ack_i;
// Hold the request until the far side acknowledges.

Sources: lowRISC §Comments

Quoting lowRISC: "each state alternative should be preceded with a comment that describes the function of that state within the state machine". Keeping the description on the arm and not on the enum member means there is one copy to keep true.

// IDLE: wait for a request; nothing is in flight.
IDLE: begin
    if (req_i) state_d = BUSY;
end

typedef enum logic [1:0] {
    IDLE,  // wait for a request
    BUSY   // transfer in flight
} state_e;

Sources: lowRISC §Finite State Machines

Quoting lowRISC: "It is always okay to deviate from the style guide by necessity, as long as that necessity is clearly justified by a brief comment". An unexplained deviation is indistinguishable from a mistake, so the next reader either breaks it or copies it.

wire tri_bus;  // Must be wire: connects to an inout port (style exception)

wire tri_bus;

Sources: lowRISC §Style Guide Exceptions

The opening condition has scrolled off screen by the time the reader reaches the close; without the label, matching them is a manual count. Verible checks both mechanically.

`ifdef SYNTHESIS
    // ...
`endif  // SYNTHESIS

`ifdef SYNTHESIS
    // ...
`endif

Sources: lowRISC §Comments, Verible

Every build system, waveform viewer and synthesis report addresses design units by name and finds them by filename. When the two disagree the mapping becomes a lookup only the author knows.

// fifo_sync.sv
module fifo_sync #(

// fifo.sv
module fifo_sync #(

Sources: lowRISC §Files, Verilator DECLFILENAME

The extension is how every tool decides whether to compile a file as a translation unit or treat it as text to be pulled into one. A header compiled standalone fails in ways that read as syntax errors far from the cause.

prim_assert.svh

prim_assert.sv  // but only ever `include`d

Sources: lowRISC §Files

Quoting lowRISC: "This makes it easier for the reader to find the declaration and see the signal type." Measured practice agrees -- 74.9% of OpenTitan declarations follow the first statement of the module. A hoisted block puts the type a screen away from every use.

// Write pointer, binary, wraps at Depth.
logic [PtrW-1:0] wptr_q, wptr_d;
always_ff @(posedge clk_i or negedge rst_ni) begin

logic [PtrW-1:0] wptr_q, wptr_d;
logic [PtrW-1:0] rptr_q, rptr_d;
logic            full, empty;
// ... 200 lines ...

Sources: lowRISC §Declarations, OpenTitan practice (74.9% near-use)

SystemVerilog has no forward declaration for package contents, so a cycle has no legal compilation order. Tools that appear to accept one are relying on file order, which changes silently when the build system does.

package top_pkg;
    import common_pkg::*;  // common_pkg imports nothing from top_pkg

package a_pkg; import b_pkg::*; endpackage
package b_pkg; import a_pkg::*; endpackage

Sources: lowRISC §Packages

A file-scope wildcard import leaks every name in the package into every design unit in the file and into anything that includes it, so a later addition to the package can capture an identifier that already resolved elsewhere. Scoping it to the module bounds the damage to one unit.

module hmac_core
    import hmac_pkg::*;
#(

import hmac_pkg::*;
module hmac_core #(

Sources: lowRISC §Packages

The non-ANSI style splits each port's direction, type and order across three places, so adding a port means three consistent edits and the compiler catches only some mistakes. One port per line is also what makes a trailing comment per port possible at all.

module fifo_sync #(
    parameter int unsigned Depth = 8  // Entries; must be a power of two
) (
    input  logic clk_i,   // System clock
    input  logic rst_ni   // Asynchronous reset, active-low
);

module fifo_sync (clk, rst_n);
    input clk;
    input rst_n;

Sources: lowRISC §Module Declaration

A fixed prefix means the reader checks the clocking and reset scheme of an unfamiliar module by looking at one place, and an instantiation's first two lines are comparable across every module in the tree.

input  logic clk_i,    // System clock
input  logic rst_ni,   // Asynchronous reset, active-low
input  logic req_i,    // Transfer request

input  logic req_i,    // Transfer request
input  logic clk_i,    // System clock
input  logic rst_ni,   // Asynchronous reset, active-low

Sources: lowRISC §Module Declaration

A positional list breaks silently when a port is inserted, and .* makes the connection depend on names matching in two files that no longer have to agree in writing -- a renamed signal connects to nothing and reports nothing. Measured practice agrees: .* appears in 28 OpenTitan files and every one of them is under dv/, fpv/, cov/ or sva/, never in synthesizable RTL.

fifo_sync u_fifo (
    .clk_i  (clk_i),
    .rst_ni (rst_ni),
    .data_i (data_i)
);

fifo_sync u_fifo (.*);
fifo_sync u_fifo (clk_i, rst_ni, data_i);

Sources: lowRISC §Module Instantiation, BSG §prohibitions, OpenTitan practice (0 uses in RTL)

An omitted port is indistinguishable from an oversight, and an unconnected input floats to z or a tool-dependent default rather than failing. Writing the tie-off states the intent where the next reader will look for it.

.status_o (),          // Unused: this instance never reports status
.debug_i  (1'b0),      // Tied off: debug hooks are not built in this config

// status_o and debug_i simply absent from the instantiation

Sources: lowRISC §Module Instantiation

defparam applies from a distance, so the effective parameter value of an instance cannot be read from the instantiation; its elaboration order is also weakly specified and it is deprecated in IEEE 1800. Named overrides keep the value where the instance is.

fifo_sync #(
    .Depth (16)
) u_fifo (

fifo_sync u_fifo ( ... );
defparam u_fifo.Depth = 16;

Sources: lowRISC §Module Instantiation, Verilator DEFPARAM

Interface-typed ports have uneven synthesis support across Vivado, Quartus, Design Compiler, Genus and Yosys, and they hide the module's real fan-in and fan-out from lint and CDC tools. Measured practice is unanimous: zero interface-typed ports in synthesizable RTL across OpenTitan, Ibex and PULP.

input  tlul_pkg::tl_h2d_t tl_i,   // TileLink host-to-device, packed struct
output tlul_pkg::tl_d2h_t tl_o    // TileLink device-to-host

tlul_if.device tl   // interface port in a reusable module

Sources: PULP practice, OpenTitan/Ibex/PULP measurement (0 uses)

The difference between these protocols is which signal is allowed to depend combinationally on which, and getting it wrong creates a combinational loop only at the point where two modules are finally connected -- often across a hierarchy boundary, long after both passed lint alone. The name is the only place the contract can live, because no linter can check it. Only ready_and and credit are safe at a top level where both ends are unknown.

output logic data_ready_and_o,  // r&v: must not depend on data_valid_i
input  logic data_valid_i       // r&v: must not depend on data_ready_and_o

output logic data_ready_o   // Which protocol? The consumer cannot tell.

Sources: BSG SystemVerilog coding standard §handshakes, Taylor et al., DAC 2018

A single case convention means a reader never has to decide whether a difference in case is meaningful. The exceptions below -- parameters, constants, macros, types -- are deliberate: each marks a category of identifier whose binding time differs from a signal's.

logic [7:0] write_data_q;

logic [7:0] writeData_q;

Sources: lowRISC §Naming Conventions

Direction is declared once in the port list but read at every use inside the module and at every connection outside it. The suffix carries it to both places, so a signal driven in the wrong direction is visible where the mistake is written rather than where it is compiled.

input  logic       req_i,    // Transfer request
output logic [7:0] data_o    // Payload

input  logic       req,
output logic [7:0] data

Sources: lowRISC §Suffixes

Without a fixed order the same signal is spelled rst_in in one module and rst_ni in the next, and the two no longer sort, grep or connect as the same name. Active-low-before-direction also keeps the direction as the true final token, which is what the linter's suffix regex anchors on.

input logic rst_ni,  // Asynchronous reset, active-low

input logic rst_in,  // same signal, different spelling

Sources: lowRISC §Suffixes

The pair makes a register visible as a register at every use, so reading a value one cycle late -- the most common RTL mistake -- becomes a spelling difference the reader can see rather than a timing property they have to reconstruct.

logic [7:0] count_q, count_d;  // Byte counter
always_comb count_d = count_q + 8'd1;

logic [7:0] count, count_next;

Sources: lowRISC §Suffixes

A declaration reads state_e state_q; -- type and variable are distinguishable without looking either up. Anonymous enums and structs cannot be named in a port list, a function signature or a package, so they force a copy of the definition at each use.

typedef enum logic [1:0] { IDLE, BUSY, DONE } state_e;  // Transfer states
state_e state_q, state_d;                               // Current/next state

enum logic [1:0] { IDLE, BUSY, DONE } state_q, state_d;

Sources: lowRISC §Naming Conventions

The case says whether overriding the value at instantiation is expected. Both spellings are accepted by the linter's CamelCase check, which matches lowRISC's own split rather than contradicting it. Measured practice: 99.8% UpperCamel across lowRISC code.

parameter  int unsigned Depth  = 8;             // Entries; override per instance
localparam int unsigned PtrW   = $clog2(Depth); // Derived, not tunable
localparam logic [7:0]  SOF_BYTE = 8'h7E;       // Protocol constant, immutable

parameter int unsigned depth = 8;

Sources: lowRISC §Naming Conventions, lowRISC practice (99.8% UpperCamel)

A negated name turns every use into a double negative -- if (!DisableLogging) -- which is where sign mistakes hide. Defaults also read wrong: DisableLogging = 0 requires two steps to mean "logging is on".

parameter bit EnableAssertions = 1;  // Compile the SVA blocks

parameter bit DisableAssertions = 0;

Sources: Verible, house style

Macros ignore every scope in the language, so the name is the only namespace they have. Undefining a file-local macro keeps it from leaking into whatever file includes this one next, where a collision would silently take the wrong definition.

`define PRIM_ASSERT__VALID(x) ...
`define _local_helper(x) ...
`undef _local_helper

`define VALID(x) ...

Sources: lowRISC §Naming Conventions

The clock-domain prefix is the load-bearing half: it makes a crossing visible at the point of assignment, so assign vdata = udata; reads as a bug on the line where it is written rather than at CDC-analysis time. Whole words matter because the reader of an abbreviation is usually not its author.

logic [7:0] uart_rx_data_q;   // uClk domain
logic [7:0] vsync_rx_data_q;  // vClk domain -- crossing is visible here

logic [7:0] urxd_q;
logic [7:0] vrxd_q;

Sources: lowRISC §Use descriptive names, Cummings SNUG-2001 §clock domain naming

SystemVerilog reserved many words that were legal Verilog-2001 identifiers, so a name that compiles today can break when a tool moves to a newer language level -- as a syntax error far from the declaration.

logic packet_type;

logic type;  // `type` is a SystemVerilog keyword

Sources: lowRISC §Naming Conventions

Bundled into one rule because none of them is a judgement call -- the formatter produces all four and a reviewer never has to discuss any of them. Four spaces match Python and make nesting depth readable at a glance; 100 columns follows the RISC-V open-source ecosystem this style descends from; 80 is too narrow once names carry direction and register suffixes.

always_comb begin
    data_d = data_i;
end

always_comb begin
	data_d = data_i;   
end

Sources: lowRISC §Basics (column limit), house style (four-space indent), Verible defaults

These constructs are read as tables -- a reader scans one column to answer "what is the width of every port" -- and alignment is what makes the column exist. Loose assignments are excluded deliberately: aligning them makes every future edit rewrite its neighbours' whitespace, which is the cost that keeps Black from aligning anything. lowRISC requires alignment only for instantiation port expressions; the rest is ours, and costs nothing because the formatter does it.

input  logic        clk_i,    // System clock
input  logic [31:0] addr_i,   // Byte address
output logic        valid_o   // Response valid

input logic clk_i, // System clock
input logic [31:0] addr_i, // Byte address
output logic valid_o // Response valid

Sources: lowRISC §Tabular Alignment, house style (the wider set)

A single-statement body that grows a second statement is a silent bug, and it is exactly the edit a model or a hurried human makes. This is stricter than lowRISC, which permits omitting begin/end when the whole statement fits on one line. Note the cost: neither the formatter nor the linter can insert begin/end, so on existing code every violation is a manual edit.

if (clear_i) begin
    count_d = '0;
end else begin
    count_d = count_q + 1'b1;
end

if (clear_i) count_d = '0;
else count_d = count_q + 1'b1;

Sources: house style (stricter than lowRISC §begin/end)

A stray semicolon after if (cond); silently makes the body empty and the following block unconditional -- it parses, simulates and synthesises, just not as written.

if (valid_i) begin
  data_d = data_i;
end

if (valid_i);
begin
  data_d = data_i;
end

Sources: Verible

SystemVerilog's precedence table places the bitwise and comparison operators in an order that surprises most readers coming from C, and the failure is a wrong-but-plausible value rather than an error.

assign hit = (tag_q == tag_i) && (valid_q | force_i);

assign hit = tag_q == tag_i && valid_q | force_i;

Sources: Verible

logic is four-state like reg and wire but carries a single-driver check the compiler enforces, so an accidental second driver is an error at elaboration instead of a resolved value that simulates as x and synthesises as a short.

logic [7:0] data_q;  // Registered payload

reg [7:0] data_q;

Sources: lowRISC §Use logic for synthesis

Cummings SNUG-2000 guideline #1. Blocking assignments in a clocked block execute in the active region of the stratified event queue, so a flop reading another flop assigned earlier in the same block sees the new value instead of the old one -- the simulation shows one pipeline stage where the synthesised gates have two, and which one you get depends on statement order.

always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        b_q <= '0;
    end else begin
        b_q <= a_q;   // Reads the OLD a_q, as the hardware does
    end
end

always_ff @(posedge clk_i) begin
    a_q = data_i;
    b_q = a_q;      // Reads the NEW a_q: one flop in sim, two in gates
end

Sources: Cummings SNUG-2000 guideline #1, lowRISC §Sequential Logic

Cummings SNUG-2000 guideline #3, plus the sensitivity-list half: always_comb is checked by the tool for completeness and for having no blocking/nonblocking mix, where always @(*) is inferred and an incomplete manual list produces a latch in synthesis that simulation does not show. Nonblocking assignments inside a combinational block defer the update to the NBA region, so a value read later in the same block is stale.

always_comb begin
    sum = a_i + b_i;
    carry = sum[8];     // Sees the value just assigned
end

always @(a_i) begin   // b_i missing: latch
    sum <= a_i + b_i;
end

Sources: Cummings SNUG-2000 guidelines #3, #10, lowRISC §Combinational Logic

Cummings SNUG-2000 guideline #5. A mixed block splits its own updates across the active and NBA regions, so the behaviour depends on the order the two kinds of statement happen to appear in -- and is not what either kind alone would give.

always_ff @(posedge clk_i) begin
    a_q <= a_d;
    b_q <= b_d;
end

always_ff @(posedge clk_i) begin
    temp = a_d;
    b_q <= temp;
end

Sources: Cummings SNUG-2000 guideline #5

Cummings SNUG-2000 guideline #6. Two blocks assigning one variable race: the simulator may execute them in either order within a time step, and synthesis resolves the conflict as a short or an arbitrary winner. The failure is order-dependent, so it often appears only after an unrelated edit.

always_comb begin
    data_d = load_i ? data_i : data_q;
end

always_comb data_d = data_i;
always_comb if (hold_i) data_d = data_q;

Sources: Cummings SNUG-2000 guideline #6

Cummings SNUG-1999 §synthesis mismatch. A signal left unassigned on some path through a combinational block must hold its previous value, which is a latch -- inferred silently, sensitive to a clock it was never meant to have, and usually found in static timing analysis rather than simulation.

always_comb begin
    valid_o = 1'b0;         // Default
    data_o  = '0;           // Default
    if (hit_i) begin
        valid_o = 1'b1;
        data_o  = payload_i;
    end
end

always_comb begin
    if (hit_i) begin
        valid_o = 1'b1;       // valid_o latches when hit_i is low
        data_o  = payload_i;
    end
end

Sources: Cummings SNUG-1999 §synthesis mismatch, lowRISC §Combinational Logic

Without a default, any unlisted value leaves the case's outputs unassigned, which infers a latch in combinational logic and leaves the state unchanged in sequential logic. unique does not substitute: it adds a runtime check in simulation but does not supply a value, and the check is absent in synthesis.

unique case (state_q)
    IDLE: state_d = req_i ? BUSY : IDLE;
    BUSY: state_d = done_i ? IDLE : BUSY;
    default: state_d = IDLE;   // Unreachable; recovers from an upset state
endcase

unique case (state_q)
    IDLE: state_d = req_i ? BUSY : IDLE;
    BUSY: state_d = done_i ? IDLE : BUSY;
endcase

Sources: Cummings SNUG-2005, lowRISC §Case Statements, Verilator CASEINCOMPLETE

An unsized literal is 32 bits wide, so comparing or assigning it silently zero-extends or truncates the other operand. Truncation of a constant is the case the compiler is least likely to warn about, because the value looks intentional.

logic [7:0] byte_q;
assign byte_q = 8'hFF;
assign wide_q = '0;        // Context width, whatever it is

logic [7:0] byte_q;
assign byte_q = 9'h1FF;    // Truncated to 8'hFF, silently

Sources: lowRISC §Number Formatting, Verilator WIDTH

Cummings SNUG-1999. casex treats x as a don't-care in the case *expression* as well as the items, so an input that is still unknown silently matches the first arm -- in his cited case an input unknown after reset release was masked in RTL simulation, gate-level simulation missed it, and the first ASIC came back flawed. casez has the same mechanism but only a floating z can trigger it, which is far less likely to mask a reset bug.

casez (opcode_i)
    8'b0000_????: op_d = OP_ALU;
    8'b0001_????: op_d = OP_LOAD;
    default:      op_d = OP_ILLEGAL;
endcase

casex (opcode_i)
    8'b0000_xxxx: op_d = OP_ALU;   // Matches when opcode_i is itself unknown
endcase

Sources: Cummings SNUG-1999 §casex

A static-lifetime function shares one copy of its locals across every call, so two concurrent calls corrupt each other -- and static is the default in a module. Explicit types stop the implicit single-bit default from silently truncating a wider argument.

function automatic logic [7:0] parity_byte(input logic [7:0] data);
    return {^data, data[6:0]};
endfunction

function parity_byte(data);
    parity_byte = {^data, data[6:0]};
endfunction

Sources: lowRISC §Functions and Tasks, Verible

A parameter in a module body is overridable through the deprecated defparam path and confuses which values are part of the module's interface. An untyped parameter takes its type from its default value, so overriding 8 with 8'sd8 silently changes the arithmetic of every expression using it.

module fifo #(
    parameter int unsigned Depth = 8       // Interface: tunable
) ();
    localparam int unsigned PtrW = $clog2(Depth);  // Body: derived

module fifo ();
    parameter Depth = 8;

Sources: lowRISC §Parameterized Modules, Verible

Mixing endianness across a design makes bit 0 mean the LSB in one module and the MSB in the next, so a part-select that looks symmetric reverses the field. A negative dimension comes from a parameter expression that underflows -- $clog2(1) is 0, so [$clog2(Depth)-1:0] is illegal at Depth = 1, which is the edge case the parameterised module is least likely to be tested at.

logic [31:0] word_q;              // Packed: big-endian
logic [7:0]  buffer_q [0:15];     // Unpacked: little-endian

logic [0:31] word_q;

Sources: lowRISC §Dimensions, Verible

Synthesis ignores delays and most system tasks rather than rejecting them, so the gates implement something the RTL simulation never showed. A # delay in RTL is also the classic way a race is hidden rather than fixed.

assign data_o = data_q;

assign #1 data_o = data_q;

Sources: Cummings SNUG-2000 guideline #8, Verible

Without it, a misspelled identifier on the left of a continuous assignment creates a one-bit implicit net rather than an error -- the design compiles, and the signal is silently stuck. lowRISC does not use the directive (zero uses across OpenTitan, Ibex and PULP) but does mandate that "A correct design contains no inferred nets"; this is that rule made mechanical.

`default_nettype none
module fifo_sync ( ... );
endmodule
`resetall

module fifo_sync ( ... );
    assign data_ou = data_q;   // typo: creates a 1-bit implicit net

Sources: house style, lowRISC §Declare all signals (states the rule, not the directive), Verilator IMPLICIT

An implicit width change is silent in both simulation and synthesis: a wider value is truncated and a narrower one is zero- or sign-extended by rules most readers cannot recite. The design compiles, and the missing top bit shows up as wrong arithmetic at the first large value. An out-of-range select reads x in simulation and an arbitrary bit in gates.

logic [3:0] nibble_o;
assign nibble_o = data_i[3:0];          // Width stated by the select
assign sum_d    = 9'(a_i) + 9'(b_i);    // Carry kept by the cast

logic [3:0] nibble_o;
assign nibble_o = data_i;               // 8 bits into 4, silently truncated

Sources: Verilator WIDTH, lowRISC §Number Formatting

An undriven net simulates as z or x and synthesis replaces it with a constant of its own choosing, usually zero, then optimises away everything that depended on it. The gates and the simulation both look plausible and disagree with each other and with the author.

logic busy_q;  // Driven by the state register below
assign busy_o = busy_q;

logic busy_q;  // Declared, never assigned
assign busy_o = busy_q;

Sources: Verilator UNDRIVEN, house style

An unused signal is either dead code or a connection that was meant to be made. The second is a bug that no other check reports, and it hides among the first unless the dead code is removed or waived where it stands.

// verilator lint_off UNUSEDSIGNAL
logic [7:0] spare_q;  // Reserved for the next revision
// verilator lint_on UNUSEDSIGNAL

logic [7:0] parity_q;  // Computed, then never connected to parity_o

Sources: Verilator UNUSEDSIGNAL, house style

IEEE 1800 evaluates an expression as signed only when every operand is signed: one unsigned operand -- a port, a part-select, a sized literal like 4'd1 -- silently makes the whole expression unsigned, so a negative value compares as a large positive one and a right shift fills with zeros. The code reads correctly and simulates wrongly only for negative inputs, which are the ones a directed test forgets.

logic signed [7:0] offset_i;
logic signed [8:0] sum;
assign sum = $signed({1'b0, base_i}) + offset_i;   // Both operands signed

logic signed [7:0] offset_i;
assign sum = base_i + offset_i;                    // base_i unsigned: all unsigned

Sources: IEEE 1800-2017 §11.8.1 (expression type rules), house style

Cummings SNUG-1999, "the evil twins". They live in comments, so the simulator ignores them while synthesis acts on them -- the design is described differently to the two tools by construction. full_case lets synthesis delete logic for values it now believes unreachable (his decoder loses its enable input entirely); parallel_case deletes a priority encoder that RTL simulation still models. They are most dangerous when they work, because nothing reports the divergence.

unique case (sel_i)
    2'b00: y_o = a_i;
    2'b01: y_o = b_i;
    default: y_o = '0;
endcase

case (sel_i)  // synopsys full_case parallel_case
    2'b00: y_o = a_i;
    2'b01: y_o = b_i;
endcase

Sources: Cummings SNUG-1999 §full_case parallel_case

Cummings SNUG-2005: these are real keywords, so simulation, synthesis and formal all read them, and they double as runtime assertions. But they are not a blanket substitute -- a default nullifies priority entirely (only unique's overlap check survives), neither removes a latch caused by unassigned outputs, and both raise runtime errors against the standard default-assign-then-partial-case idiom.

unique case (state_q)
    IDLE: state_d = BUSY;
    BUSY: state_d = IDLE;
    default: state_d = IDLE;
endcase

priority case (state_q)
    IDLE: state_d = BUSY;
    default: state_d = IDLE;   // `default` makes `priority` mean nothing here
endcase

Sources: Cummings SNUG-2005 §unique & priority

The construct states the designer's intent to every downstream tool and reader. A priority chain written as a case invites someone to add parallel_case later to "optimise" it, which is exactly the bug SYN-001 describes.

if (err_i) begin
    resp_d = RESP_ERR;
end else if (valid_i) begin
    resp_d = RESP_OK;
end

case (1'b1)
    err_i:   resp_d = RESP_ERR;   // Overlapping arms in a `case`
    valid_i: resp_d = RESP_OK;
endcase

Sources: Cummings SNUG-1999

Elaboration of a recursive hierarchy terminates only if the tool can prove the parameter sequence reaches the base case, and the tools disagree about which expressions they can prove. What elaborates in one synthesiser hangs in the next.

// Write the recursion as a generate-for over a flat array of stages.

module tree #(parameter int N = 8) ();
    tree #(.N(N/2)) u_left ();

Sources: lowRISC §Generate Constructs

A combinational loop has no stable value to settle to, or several; it oscillates or latches depending on gate delays that neither simulation nor static timing analysis models. RTL simulation usually shows a plausible value or a delta-cycle limit, and the synthesis tool breaks the loop wherever it likes. The usual source is two always_comb blocks, or a ready/valid pair, that each read what the other drives.

assign ready_o = ~full_q;          // Depends only on a flop

assign ready_o = valid_i & ~stall; // stall is computed from ready_o
assign stall   = ready_o & busy_i;

Sources: Yosys check, house style

ASIC synthesis ignores initial blocks, so a design that relies on one simulates from a value the silicon never has, and the first sign is a chip that does not come out of power-on the way the testbench did. FPGA flows do honour initial values for registers, which is why this is a SHOULD: a deliberate FPGA-only use carries a waiver saying so.

always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        count_q <= '0;       // Starting value from reset

initial count_q = '0;    // Ignored by ASIC synthesis

Sources: IEEE 1800-2017 §9.2.1 (initial procedures), house style

This is the ecosystem's convention and measurement confirms it is followed, not just written: 902 of 959 reset always_ff blocks in OpenTitan and 108 of 130 in Ibex use async active-low, with exactly one positive-edge async reset in all of OpenTitan's hw/ip. Active-low matters physically -- a reset asserted by a pin being pulled low survives loss of the driver. Note that BSG argues the opposite (synchronous, high-true) precisely to avoid the de-assertion hazard RST-002 addresses; this style takes the async path and mandates the synchroniser instead.

always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        count_q <= '0;
    end else begin
        count_q <= count_d;
    end
end

always_ff @(posedge clk_i) begin
    if (rst) begin      // synchronous, active-high
        count_q <= '0;

Sources: lowRISC §Resets, Cummings SNUG-2003 §reset techniques, OpenTitan/Ibex measurement (94.1% / 83.1%)

Cummings SNUG-2003, verbatim: "EVERY ASIC USING AN ASYNCHRONOUS RESET SHOULD INCLUDE A RESET SYNCHRONIZER CIRCUIT!!" Assertion is safe because it bypasses the clock path. Removal is the bug, two ways: de-asserting inside a flop's reset *recovery* window leaves it metastable, so the chip silently loses its reset state -- an intermittent field failure the controlled simulation never reproduces; and an asynchronous removal lets clock- and reset-tree skew release some flops a cycle before others, starting the design in a state nobody simulated. The synchroniser collapses this into one closed timing budget.

// Reset synchroniser: async assert, sync de-assert into clk_i.
always_ff @(posedge clk_i or negedge rst_ext_ni) begin
    if (!rst_ext_ni) begin
        {rst_q, rst_meta_q} <= 2'b00;
    end else begin
        {rst_q, rst_meta_q} <= {rst_meta_q, 1'b1};
    end
end

// External async reset driven straight into every flop in the domain.
always_ff @(posedge clk_i or negedge rst_ext_ni) begin

Sources: Cummings SNUG-2003 §reset synchronizer

A reset de-asserted synchronously to one clock is asynchronous to every other, so sharing one synchroniser reintroduces exactly the recovery-window failure it was there to prevent -- in the domains nobody looked at.

rst_sync u_rst_sync_sys  (.clk_i(sys_clk_i),  .rst_ni(rst_ext_ni), .rst_no(sys_rst_ni));
rst_sync u_rst_sync_usb  (.clk_i(usb_clk_i),  .rst_ni(rst_ext_ni), .rst_no(usb_rst_ni));

// One synchroniser in the sys domain; usb flops use sys_rst_ni.

Sources: Cummings SNUG-2003

Every reset flop costs a reset-tree endpoint, routing and a larger cell, and the reset tree is one of the hardest nets to close timing on. A datapath register whose value is qualified by a valid bit does not need a defined value at startup, because nothing reads it until the valid bit says so.

always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        valid_q <= 1'b0;      // Control: reset
    end else begin
        valid_q <= valid_d;
    end
end
always_ff @(posedge clk_i) begin
    data_q <= data_d;       // Datapath: qualified by valid_q, not reset
end

// Every flop in a 512-bit datapath tied to the reset tree.

Sources: Xilinx UG949 §reset strategy, OpenTitan practice (57 unreset always_ff blocks)

A net that reaches both a reset pin and a data pin cannot be timed as either, and the synthesis tool picks one. A clock gated by if (en) in RTL produces glitches on the gated clock that the RTL simulation cannot show, because RTL has no notion of a glitch.

prim_clock_gating u_cg (
    .clk_i    (clk_i),
    .en_i     (enable_q),
    .clk_o    (clk_gated)
);

assign clk_gated = clk_i & enable_q;   // Glitches on every enable change

Sources: Cummings SNUG-2001, Verilator SYNCASYNCNET

Cummings SNUG-2003 §SystemVerilog FSM. A typed enum gives the tool a closed set of legal values, so an assignment of an out-of-range constant is an error and waveform viewers show state names instead of numbers. Macros have no type, no scope and no tool visibility.

typedef enum logic [1:0] { IDLE, BUSY, DONE } state_e;  // Transfer states
state_e state_q, state_d;                               // Current/next state

`define IDLE 2'b00
logic [1:0] state;

Sources: Cummings SNUG-2003 §SystemVerilog FSM, lowRISC §Finite State Machines

Cummings SNUG-2000 §FSM. Separating the register from the next-state logic means the reset, the clocking and the state transition each appear exactly once, and the combinational block can be read as a pure function of current state and inputs. A single-block FSM makes every output a registered output whether or not that was intended.

// State register.
always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        state_q <= IDLE;
    end else begin
        state_q <= state_d;
    end
end

// Next-state and output logic.
always_comb begin
    state_d = state_q;
    ...
end

always_ff @(posedge clk_i) begin
    case (state_q)
        IDLE: if (req_i) begin state_q <= BUSY; out_q <= 1'b1; end

Sources: Cummings SNUG-2000 §FSM coding styles

Cummings SNUG-2000. A combinational output depends on the FSM's inputs in the same cycle, so it arrives late and its timing path continues into whatever the consumer does with it -- a path that neither module's timing constraints describe on its own.

always_ff @(posedge clk_i or negedge rst_ni) begin
    if (!rst_ni) begin
        grant_o <= 1'b0;
    end else begin
        grant_o <= (state_d == GRANTED);
    end
end

assign grant_o = (state_q == IDLE) && req_i;   // Mealy, leaves the module

Sources: Cummings SNUG-2000 §FSM outputs

Two FSMs in one module share a namespace and a reset block, so their states, transitions and outputs interleave in the source and neither can be read on its own. Splitting them also makes each one's interface -- and therefore its contract -- explicit.

// arbiter_fsm.sv and refill_fsm.sv, instantiated side by side.

// One module holding state_q and mode_q, each a separate FSM.

Sources: Cummings SNUG-2000, lowRISC §Finite State Machines

Cummings SNUG-2001. Across asynchronous domains a setup/hold violation on the first flop is a certainty, not a risk -- the phase relationship changes continuously. The second flop gives the first a full clock period for metastability to decay before anything samples it. Without it, a metastable output fans out and different gates resolve it differently, so the design disagrees with itself.

always_ff @(posedge dst_clk_i or negedge dst_rst_ni) begin
    if (!dst_rst_ni) begin
        {sync_q, meta_q} <= 2'b00;
    end else begin
        {sync_q, meta_q} <= {meta_q, src_signal_i};
    end
end

always_ff @(posedge dst_clk_i) begin
    captured_q <= src_signal_i;   // One flop: metastability reaches the logic
end

Sources: Cummings SNUG-2001 §synchronizers

Cummings SNUG-2001, and the most expensive mistake in this family because every bit is individually correct. Bit-to-bit skew from routing, rise/fall differences and across-die process variation cannot be matched away; a destination edge landing inside that skew window captures some bits this cycle and the rest next cycle, latching a word that never existed in the source. The same breaks paired controls -- a load and an enable arriving in different cycles means nothing loads.

// Gray-coded pointer: only one bit changes per increment, so a skewed
// capture yields either the old or the new value, never a third.
prim_fifo_async u_cdc_fifo ( ... );

for (genvar i = 0; i < 8; i++) begin : gen_sync
    prim_flop_2sync u_sync (.d_i(data_i[i]), .q_o(data_sync[i]));
end

Sources: Cummings SNUG-2001 §multi-bit signals

Cummings SNUG-2001/2002, in his order of preference. Each pattern removes the skew problem a different way: consolidation leaves nothing multi-bit to skew; the held-stable formulation guarantees the bus is not changing while it is sampled; Gray coding guarantees at most one bit differs between consecutive values; the FIFO does the pointer crossing in Gray code and keeps the data in memory that is never crossed at all.

// MCP: data held stable while a synchronised enable qualifies it.
assign data_stable_d = load_i ? data_i : data_stable_q;
prim_flop_2sync u_en_sync (.d_i(load_toggle_q), .q_o(load_toggle_sync));

// A free-running binary counter synchronised straight across.

Sources: Cummings SNUG-2001, Cummings SNUG-2002 §async FIFO

Cummings SNUG-2001. Combinational output settles through a sequence of intermediate values, and every one of them is a potential edge for the destination to capture -- the crossing sees phantom pulses that never existed as logical values. Registering also improves MTBF by cutting how often the crossed signal changes.

always_ff @(posedge src_clk_i) begin
    req_q <= req_valid && !busy;   // Registered, then crossed
end

assign req_cross = req_valid && !busy;   // Glitches cross as real edges

Sources: Cummings SNUG-2001

Cummings SNUG-2001. A pulse shorter than the destination period can fall entirely between two destination edges and be missed, and one sampled near an edge may be captured by the first flop but not held long enough for the second. Three edges is the width that guarantees capture regardless of phase.

// Toggle: the level survives any number of destination periods.
assign req_toggle_d = req_i ? ~req_toggle_q : req_toggle_q;

// A single source-clock-wide pulse crossing into a slower domain.

Sources: Cummings SNUG-2001

Cummings SNUG-2001. Confining crossings makes them findable -- the set of modules to review for CDC is a list rather than a search -- and it lets the rest of the design be verified, timed and lint-checked as single-clock logic.

// cdc_sync.sv, cdc_fifo.sv instantiated at the top; leaves are single-clock.

// A leaf module taking both sys_clk_i and usb_clk_i.

Sources: Cummings SNUG-2001 §partitioning

The label becomes part of the hierarchical path of everything inside it. Without one the tool invents a name like genblk3, so waveforms, timing reports, constraints and bug reports all address the logic by a number that shifts when an unrelated generate is added above it.

for (genvar i = 0; i < NumPorts; i++) begin : gen_port
    prim_fifo_sync u_fifo ( ... );
end

for (genvar i = 0; i < NumPorts; i++) begin
    prim_fifo_sync u_fifo ( ... );
end

Sources: lowRISC §Generate Constructs, Verible

The generate region has been optional since Verilog-2001 and adds a scope level that changes hierarchical paths without changing behaviour. An inline genvar scopes the loop variable to its loop, so two loops in one module cannot collide.

for (genvar i = 0; i < N; i++) begin : gen_stage
    ...
end

genvar i;
generate
    for (i = 0; i < N; i++) begin : gen_stage
        ...
    end
endgenerate

Sources: lowRISC §Generate Constructs, Verible

A parameterised module is instantiated by people who did not read it. A power-of-two depth assumption that is violated produces wrong hardware rather than an error, and the failure appears as a functional bug in the instantiating design, far from the module that assumed it.

`ASSERT_INIT(DepthIsPowerOfTwo_A, (Depth & (Depth - 1)) == 0)

parameter int unsigned Depth = 8;  // must be a power of two (comment only)

Sources: lowRISC §Parameterized Modules

The macros carry the clock and reset arguments, the severity, and the `ifdef guards that keep assertions out of synthesis. Bare assertions have to repeat all of that at every site, and the one that forgets the reset guard fires spuriously during reset in every simulation.

`ASSERT(ReqStableUntilAck_A, req_o && !ack_i |=> req_o, clk_i, !rst_ni)

assert property (@(posedge clk_i) req_o && !ack_i |=> req_o);

Sources: lowRISC §Assertions, PULP assertions.svh

X propagates silently through most RTL operators and is optimistically resolved by others, so an X originating in one module is often first noticed as wrong data several modules downstream. Checking at the boundary localises it to the module that produced it.

`ASSERT_KNOWN(ValidKnown_A, valid_o)

// No X checks; an uninitialised counter shows up as wrong data three
// modules away.

Sources: lowRISC §Assertions

Every check in this guide is cheap at the point of writing and expensive later: a latch found by static timing analysis, a width truncation found in a chip bring-up lab, a missing case default found by a customer. The gate exists so that none of them travels.

$ svstyle check fifo_sync.sv && verilator --lint-only -Wall fifo_sync.sv

// Committed with 14 SHOULD findings and 2 MUSTs outstanding.

Sources: house style