hdl-tools/digital-chip-design-agents/rtl-design

Skill: RTL Design (SystemVerilog)

Invocation

When this skill is loaded and a user presents an RTL design task, do not execute stages directly. Immediately spawn the digital-chip-design-agents:rtl-design-orchestrator agent and pass the full user request and any available context to it. The orchestrator enforces the stage sequence, loop-back rules, and sign-off criteria defined below.

Use the domain rules in this file only when the orchestrator reads this skill mid-flow for stage-specific guidance, or when the user asks a targeted reference question rather than requesting a full flow execution.

Pre-run Context

Before executing or advising on any stage, read the following files if they exist:

1. memory/rtl-design/knowledge.md — known failure patterns, successful tool flags, PDK/tool quirks.

Incorporate its guidance into every stage decision. If absent, proceed without it.

1. memory/rtl-design/run_state.md — current run identity (run_id, design_name, tool,

last_stage). Use this to resume correctly after interruption. If absent, a new run is starting; the orchestrator will create this file before the first stage.

This pre-run read applies whether this skill is loaded by a user or called by the orchestrator mid-flow. It ensures the fix database is consulted before any diagnosis step.

Purpose

Guide RTL development from module hierarchy planning through lint-clean, CDC-clean, synthesis-ready RTL. Enforces industry-standard SystemVerilog coding practices and produces a signed-off RTL package ready for simulation and synthesis handoff.

Supported EDA Tools

Open-Source

• Verilator (verilator --lint-only) — fast lint and simulation
• Slang (slang) — modern, standards-compliant SV parser and elaborator; lint with

slang -Weverything --ignore-unknown-modules (full elaboration — see lint_check rule 6)

• Surelog (surelog) — SystemVerilog pre-processor and front-end for Yosys
• sv2v (sv2v) — SystemVerilog-to-Verilog converter; the front-end check (lint_check

rule 15) parses its output with the tool that consumes it

• Icarus Verilog (iverilog) — Verilog/SV simulator for quick sanity checks

Proprietary

• Synopsys SpyGlass (spyglass, dialect synopsys) — lint, CDC, RDC, and clock-domain analysis
• Cadence JasperGold CDC (jg, dialect cadence) — formal CDC verification
• Siemens Questa CDC (vsim, dialect siemens) — CDC analysis and sign-off

Stage: module_planning

Domain Rules

1. Top-down decomposition: start with top-level module, recurse to leaf cells
2. Each module: single clear responsibility (single responsibility principle)
3. Define all port lists before coding (direction, width, type)
4. Identify all clock domains per module; mark CDC crossings explicitly
5. Identify all reset domains; mark synchronous vs asynchronous
6. Parameterise widths and depths wherever possible
7. No logic in top-level integration modules — wiring only
8. Separate datapath and control into distinct sub-modules

Output Required

• Module hierarchy tree
• Module descriptor (name, purpose, clock domain, ports, sub-modules) per module
• Interface/port list document

Stage: rtl_coding

Scope: the rules in this stage govern synthesisable RTL. Testbenches (*_tb.sv, tb_*.sv, anything under tb/), bind-only assertion files and simulation-only behavioural models are out of scope — initial, #delay and blocking assignments are correct there, and the functional-verification skill carries the coding rules for them.

Domain Rules — General

1. Always use logic type (not wire/reg distinction)
2. All ports: explicitly typed and directioned
3. default_nettype none at top of every file
4. No latches: all always_comb blocks must have complete case and assignment coverage
5. No blocking assignments (=) in always_ff blocks
6. No non-blocking assignments (<=) in always_comb blocks
7. One always block per register or coherent register group
8. Reset all registers explicitly; synchronous reset preferred for ASIC

Domain Rules — Naming Conventions

• Clocks: clk_[domain]
• Resets: rst_n_[domain] (active-low) or rst_[domain]
• Active-low: signal_n suffix
• Registered: signal_q suffix
• Next-state: signal_d suffix
• Parameters: UPPER_SNAKE_CASE
• Modules/Signals: lower_snake_case
• Port direction: _i / _o suffixes are permitted, not required

Precedence: these conventions are this suite's project standard for new RTL. When modifying an existing file, match that file's conventions instead — one block in a different style is a worse outcome than the deviation — and record the difference as informational, not as a lint finding.

Domain Rules — Synthesis Safety

1. No delays (#) in RTL — simulation only
2. No initial blocks for logic in ASIC RTL. One exception: an elaboration-time parameter

assertion (initial + $fatal on an illegal parameter value), wrapped in // synthesis translate_off / // synthesis translate_on so it is never read as synthesised logic. A parameterised block must refuse to elaborate on a value it cannot implement (e.g. a gray-coded FIFO at a non-power-of-two depth) rather than build broken logic

1. No casex; casez only with a written justification; no full_case / parallel_case

pragmas. Write don't-care decodes as explicit case items

1. Flag any net with fanout > design_state.constraints.timing.fanout_max (default: 32) for buffering intent review
2. No combinational loops — will cause synthesis errors
3. Pipeline registers: clearly marked with _q suffix at each stage
4. FSM case policy — pick one per FSM and state it in a comment:

• Default: plain case with a default arm that goes to a recovery or error state.

Illegal states are reachable in silicon (SEU, X during bring-up); the FSM must not wedge

• Alternative: unique case with no default, plus a concurrent assertion that covers

illegal-state recovery. Keeps the simulation/formal uniqueness check

• Never unique case together with default: unique asserts the illegal state cannot

occur, default exists to recover when it does (slang: -Wcase-redundant-default)

Domain Rules — CDC

1. Two-FF synchroniser for every single-bit CDC crossing
2. Async FIFO for multi-bit CDC data paths
3. Gray-coded pointers for async FIFO crossing
4. Never sample asynchronous data directly in synchronous logic

Domain Rules — Scan Readiness

RTL that blocks scan is cheapest to fix here; the DFT flow can only report it after insertion.

1. No RTL-generated clocks (assign gclk = clk & en;): flops behind one are unreachable in

scan mode. Use a flop enable, or a library clock-gate cell with a test-enable input (Power Intent rule 5)

1. Every asynchronous set/reset must be controllable from a primary input in test mode. A

reset derived from internal logic cannot be held inactive during scan shift — give it a scan_mode bypass to the top-level reset

1. No asynchronous set/reset generated from combinational logic
2. No on-chip tri-state buses — contention is untestable; use a mux
3. A deliberate latch (lockup latch, clock-gate cell internals) is instantiated as a library

cell and waived by instance name in lint_waivers.csv, never inferred from RTL

Domain Rules — Power Intent (Clock Gating)

Apply these rules for every clock domain. Read clock_power_budget from the architecture hand-off package. For orchestrated Architecture → RTL runs, the `clock_power_budget` table is a required handoff contract; if missing, treat as a handoff violation and abort with a clear error directing the user to notify upstream packaging. For non-orchestrated or local RTL-only runs, classify domains using toggle-count estimates from Verilator simulation as a fallback.

1. High gating opportunity domains (α < design_state.constraints.power.activity_factors.default (default: 0.15) from architecture, or toggle rate below that threshold from Verilator): insert an ICG cell (CLKGATETST_X* or technology-equivalent) at the outermost clock enable boundary. Do not rely on synthesis to infer clock gates — explicit ICG insertion at RTL is required.
2. Moderate gating opportunity domains (activity_factors.default ≤ α < activity_factors.high (defaults: 0.15–0.40)): insert ICG at the sub-block level for any register file or datapath wider than 32 bits.
3. Always-on domains (α ≥ activity_factors.high (default: 0.40), or documented as always-on in architecture hand-off):

no ICG required; add a /* always-on: <reason> */ comment at the clock port declaration.

1. ICG enable signal: must be registered (setup-timing safe); combinational enable

is a lint error.

1. ICG cells: use only library-approved cells (CLKGATETST_* for testability with

scan-enable override); do not use behavioural if (enable) clk_gated = clk constructs.

1. After inserting ICGs, measure clock_gating_coverage:

coverage = (register bits behind an ICG) / (total register bits in domain) × 100% Report this metric in the rtl_signoff output.

Supported Tools for Power Intent

Output Required

• RTL source files (.sv) per module
• SVA assertion files per module
• Inline comments on all non-obvious logic
• Unverified-claims entries: each CDC, reset, FSM, protocol, arithmetic or parameter

conclusion reached in review without a tool run, appended to the unverified-claims list (see rtl_signoff) now, not at sign-off

• clock_gating_coverage metric per domain (appended to sign-off record)

Stage: design_input_check

A lint tool reports on the files it was given. This stage checks that those are the intended files before any lint message is read as a statement about the RTL. It edits nothing: its only outputs are a report and a PASS or FAIL.