lowrisc.yaml

# lowRISC SystemVerilog style guide convention rules for svlens conn.
#
# Reference: https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md
#
# Coverage: this YAML drives ConventionChecker which currently
# inspects PORT NAMES + INSTANCE NAMES from the slang ConnectionGraph.
# Rules outside that surface (always_ff vs always, anonymous enums,
# typedef names, parameter case, line length, etc.) require future
# extensions. The "Coverage gaps" section at the bottom of this file
# documents what is NOT yet enforced so you can read the full lowRISC
# guide for human review of the unchecked areas.
#
# Usage:
#   svlens conn rtl/*.sv --top your_top \
#       --check-convention --convention examples/styles/lowrisc.yaml
#
# All rule violations are reported at Severity::INFO. The conn-mode
# exit code is the active-issue count, capped at 255 -- so style-only
# violations DO contribute. Use a waiver file or `2>/dev/null` if you
# want a non-blocking lint pass.

# ─── Direction suffixes (lowRISC actual) ───────────────────────────
# lowRISC uses _i / _o / _io SUFFIXES on module ports, NOT prefixes.
# Differential-pair markers (`_p` / `_n`) compound with the direction
# marker, so output_suffix accepts `_o`, `_po`, `_no`. Comma-separated
# values give the alternative-suffix list.
# Examples (all GOOD):
#   clk_i, rst_ni, d_i, q_o, data_i, valid_i, ready_o, driver_io,
#   lvds_po, lvds_no
input_suffix: "_i,_pi,_ni"
output_suffix: "_o,_po,_no"
inout_suffix: "_io"

# Set the prefix fields empty so the checker accepts suffix-only
# naming. (Setting both prefix AND suffix would accept either.)
input_prefix: ""
output_prefix: ""

# ─── Instance prefix ────────────────────────────────────────────────
# lowRISC examples show both `i_<name>` and `u_<name>` styles. The
# guide does not mandate a single form; OpenTitan uses `u_`. Set
# this to whichever convention your project picked.
# Note: instance_prefix accepts only a single value (no list form).
# Passing "u_,inst_" is interpreted as a literal prefix, NOT as
# alternation; pick one prefix per project.
instance_prefix: "u_"

# ─── Clock / reset patterns ────────────────────────────────────────
# Default clock is `clk_i` (port) or `clk` (internal); multiple
# clocks add a domain suffix: clk_dram, clk_axi, etc.
clock_pattern: "^clk(_[a-z0-9]+)*_i?$"

# Default reset `rst_n` (internal) or `rst_ni` (port). Domain-
# suffixed resets like rst_domain_n / rst_domain_ni are also
# accepted.
reset_pattern: "^rst(_[a-z0-9]+)*_n[i]?$"

# ─── Active-low suffix ─────────────────────────────────────────────
# lowRISC marks active-low signals with `_n` (or `_ni` on inputs).
# This rule fires when an INPUT port carries the suffix but is NOT
# a recognized reset/clock pattern. Output `lvds_no` (differential)
# is automatically excluded because the rule scopes to inputs.
active_low_suffix: "_n"

# ─── Lowercase + snake_case ────────────────────────────────────────
# lowRISC requires lowercase snake_case for all signal/port names.
# Catches `dataIn` / `MyPort` / `WriteReady` style violations.
lowercase_port_names: true

# ─── Pipeline _q / _d markers ──────────────────────────────────────
# lowRISC uses `<name>_q` for registered output, `<name>_d` for the
# combinational input feeding the FF. Pipeline stages add a digit:
# `_q2`, `_q3`. These are recorded for future ConventionChecker
# extensions; the current implementation does not yet inspect
# internal nets or always_ff bodies.
reg_output_suffix: "_q"
comb_input_suffix: "_d"

# ─── Reject `_<digit>` suffix on signal names ─────────────────────
# lowRISC: "Avoid `foo_1`, `foo_2`-style suffixes". Pipeline stages
# should chain off `_q` (e.g., `foo_q2`, `foo_q3`).
reject_digit_only_suffix: true

# ─── Parameter / typedef conventions ───────────────────────────────
# Documented for forward compatibility. ConventionChecker currently
# operates on port names only -- parameter and typedef checks await
# a ConnectionExtractor enhancement that captures Parameter/Typedef
# symbols from the slang AST.
#
# lowRISC: parameters use UpperCamelCase, package-level constants
# may use ALL_CAPS, typedef structs/unions end with `_t`,
# typedef enums end with `_e`.
parameter_case_pattern: "^[A-Z][a-zA-Z0-9]*$"
typedef_suffix_pattern: "_(t|e)$"

# ----------------------------------------------------------------------
# Source-text rules (US-39E) - line-level checks against the raw bytes
# of the source file.  All opt-in; remove / set to 0 / set to false to
# disable the corresponding rule.
max_line_length: 100        # lowRISC §11.1: 100-column limit
prohibit_hard_tabs: true    # lowRISC §11.2: spaces only, no tabs
prohibit_trailing_whitespace: true  # lowRISC §11.3: no trailing WS

# File-naming rules (US-39F) - file-system-level checks.
prohibit_multiple_modules_per_file: true  # lowRISC §3.1
enforce_file_module_match: true           # lowRISC §3.2: basename == module

# ─── Coverage gaps (NOT yet enforced) ──────────────────────────────
# Round 38/39 closed most of the AST/source-text rules.  The list
# below tracks lowRISC sections that the current ConventionChecker
# still does not enforce; these remain manual-review items.
# See `docs/releases/v0.3.2.md` for the precise list of what IS
# covered today.
#
# * Function `automatic` only; tasks prohibited in RTL
# * `_p`/`_n` differential pair signals must come together
# * No hierarchical references in RTL
# * No `defparam`, `#delay`, positional parameter lists
# * `inout` port prohibition (signal direction must be in/out)
# * Blocking assignment prohibition inside always_ff
# * Multiple drivers / non-resettable FF detection