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.
2. 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
3. No casex; casez only with a written justification; no full_case / parallel_case pragmas. Write don't-care decodes as explicit case items
4. Flag any net with fanout > design_state.constraints.timing.fanout_max (default: 32) for buffering intent review
5. No combinational loops — will cause synthesis errors
6. Pipeline registers: clearly marked with _q suffix at each stage
7. 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)
2. 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
3. No asynchronous set/reset generated from combinational logic
4. No on-chip tri-state buses — contention is untestable; use a mux
5. 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.
4. ICG enable signal: must be registered (setup-timing safe); combinational enable is a lint error.
5. ICG cells: use only library-approved cells (CLKGATETST_* for testability with scan-enable override); do not use behavioural if (enable) clk_gated = clk constructs.
6. 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.

Domain Rules

1. Resolve and print the absolute path of the filelist the tool will read, and of the project or config file that selected it. Where several candidates exist (a managed project file and a user-override directory, two filelists of the same name), state which one the tool uses and why. A stale override directory silently bypasses the managed project file and every variable it would have set
2. Resolve every include directory to an absolute path, in search order. Include search is first-match-wins: a file name that exists in two include directories with different content is an ERROR, not a warning — the tool silently uses the first and ignores the second. Name the file, every directory that holds it, and the one that wins
3. Flag include directories and sources that resolve outside the declared design root, and sibling trees reachable from the include set: X beside X_v2, X_old, X_bak, or parallel version directories that hold the same file names
4. For generated inputs (register-map headers, IP configuration headers): exactly one generation's output tree is on the include path, and it is newer than its generator source
5. Every path in the filelist exists. A missing include directory is an ERROR: the tool falls through to the next directory that has the file
6. Where the input set is a .f filelist, run check_design_inputs.py (in this skill's directory) and report its JSON: python3 check_design_inputs.py <filelist.f> --root <design root> [--env NAME=VALUE] [--generated OUT_DIR=SOURCE]. It applies rules 2, 3 and 5, rule 4's age check for each --generated pair, and rule 8 with --rtl-dir and --list. Rule 1, and any flow driven by a vendor project file instead of a .f filelist, is checked by hand against the rules above
7. On FAIL, change no design file. The fix is in the input set — usually one line of a filelist — and choosing between two trees is the owner's decision: report failure_class: "input_setup", suggested_next_step: "escalate", the file, both absolute paths and the line to change. Never loop back to rtl_coding — the one exception is rule 8's registration of a module this run added
8. Registration: every module on disk must reach every tool. Projects keep separate source lists for simulation, lint, synthesis, PD and formal, often as Makefile variables, and a module missing from one of them is black-boxed by converters and synthesisers (sv2v, yosys) without an error — the simulation regression cannot notice, because it reads a different list. Enumerate every source list that feeds a tool in the project, dump any kept in a Makefile variable to a file (make -s --eval='print-%:;@echo $($*)' print-<VAR> > <var>.f), and run python3 check_design_inputs.py <filelist.f> --rtl-dir <rtl dir> --list <name>=<file> ... [--exempt <list>:<module>]. Each module_not_in_list is an ERROR naming the list and the file. Exempt a module only with a stated reason (a simulation-only model absent from the PD list). This is the one design_input_check failure that is not escalated: when the module was added by this run, adding it to the list is this run's job — a list edit, no RTL edit. A pre-existing module missing from a list, or a list you cannot edit, is input_setup per rule 7

QoR Metrics to Evaluate

• Modules on disk missing from a tool's source list, not exempted: must be 0
• Include file names present in two directories with different content: must be 0
• Missing filelists, include directories and sources: must be 0
• Generated output trees on the include path, per generator: exactly 1
• Sibling trees, paths outside the design root, identical duplicate headers: review each; proceed only with the reason recorded

Output Required

• Design-input report: absolute filelist and config paths, ordered absolute include directories, and every finding with the paths it names
• Registration report: every source list checked, each module missing from one, and each exemption with its reason
• Stage status: PASS, or FAIL with failure_class: "input_setup"

---

Stage: lint_check