Skip to content

bjwanneng/veriflow-cc / src/claude_skills/vf-rtl

vf-rtl

Verified

FileKindSize
SELF_IMPROVE.mdmarkdown3.8 KB
SKILL.mdskill md11.2 KB
SKILL_INDEX.mdmarkdown5.5 KB
analysis/bug_pattern_match.pyscript26.9 KB
analysis/corner_case_generator.pyscript4.9 KB
analysis/coverage_analyzer.pyscript5.3 KB
analysis/design_graph.pyscript8.9 KB
analysis/expected_trace_gen.pyscript12.5 KB
analysis/timing_contract_checker.pyscript25.4 KB
analysis/timing_diagnostic.pyscript21.1 KB
analysis/vcd2table.pyscript31.3 KB
bug_patterns.mdmarkdown23.2 KB
coding_style.mdmarkdown9.4 KB
core/init.pyscript13.8 KB
core/rtl_utils.pyscript7.5 KB
core/state.pyscript38.9 KB
design_rules.mdmarkdown2.9 KB
error_recovery.mdmarkdown7.0 KB
kb/knowledge_base.pyscript11.7 KB
kb/reference_kb.pyscript5.6 KB
kb/self_improve.pyscript24.4 KB
references/arbiter_round_robin.vother1.4 KB
references/counter.vother545 B
references/fifo.vother1.3 KB
references/fsm_moore.vother847 B
references/handshake_valid_ready.vother1.1 KB
references/pipeline_aligner.vother760 B
runners/benchmark_runner.pyscript23.6 KB
runners/cocotb_runner.pyscript26.3 KB
runners/iverilog_runner.pyscript26.3 KB
runners/yosys_equiv.pyscript14.2 KB
stage1_spec_golden.mdmarkdown6.1 KB
stage2_codegen.mdmarkdown5.9 KB
stage3_verify_fix.mdmarkdown17.0 KB
stage4_lint_synth.mdmarkdown6.3 KB
templates/cocotb_template.pyscript42.4 KB
templates/golden_model_template.pyscript8.7 KB
templates/spec_template.jsonconfig8.5 KB
templates/tb_integration_template.vother12.4 KB
verify/candidate_selector.pyscript7.0 KB
verify/formal_prove.pyscript12.1 KB
verify/synth_score.pyscript4.4 KB

coding_style.md

View on GitHub
# Verilog-2005 Coding Style (Condensed for AI Translation Path)

**Context**: vf-coder translates golden_model.py algorithms + spec.json timing contracts into
Verilog-2005. This document covers rules for AI-translated modules.

## 1. File Structure

```verilog
`resetall
`timescale 1ns / 1ps
`default_nettype none

module xxx #( ... )( ... );
// ... body ...
endmodule

`resetall
```

- One module per file; filename matches module name.
- ASCII only, UNIX line endings.

## 2. Formatting

4-space indent, max 100 chars per line. No tabs.
`begin` on same line as keyword. `end` on new line; `end else begin` on one line.

## 3. Naming

| Construct | Style |
|-----------|-------|
| Modules/instances | `lower_snake_case` |
| Signals | `lower_snake_case` — whole words |
| parameter/localparam | `ALL_CAPS` |

Signal suffixes: `_reg` (clocked state), `_next` (combinational next-state).

## 4. Clock and Reset

- Main clock: `clk`. Additional: `clk_<domain>`.
- **Synchronous active-high** reset named `rst`. Place `if (rst)` at the **beginning** of sequential block (reset-first + else). This guarantees reset takes priority over `_next` assignments.

```verilog
always @(posedge clk) begin
    if (rst) begin
        state_reg <= STATE_IDLE;
    end else begin
        state_reg <= state_next;
    end
end
```

## 5. Module Declaration

Verilog-2001 ANSI style. Clocks first, then reset, then all others.
Declare `wire` type on all ports explicitly.

## 6. Signal Declarations

| Driven by | Declare as |
|-----------|------------|
| `always` block | `reg` |
| `assign` / combinational | `wire` |

Assign initial values to all `reg` at declaration: `reg [7:0] data_reg = {8{1'b0}};`.

## 7. Two-Block Separation

```verilog
always @* begin           // combinational — blocking (=)
    state_next = state_reg;
    // defaults at top, then conditional logic
end

always @(posedge clk) begin // sequential — non-blocking (<=)
    state_reg <= state_next;
    if (rst) state_reg <= STATE_IDLE;
end
```

- Default values at top of `always @*` prevents latches.
- **MUST NOT** mix `=` and `<=` in same block.
- **One reg, one always block**: every `reg` must be driven by exactly one
  `always` block. Multiple always blocks writing the same `reg` causes
  undefined simulation behavior and synthesis "multiple drivers" errors.
  All register logic (FSM state, counters, control flags, data pipeline)
  goes in the single `always @(posedge clk)` block.

## 8. FSM Structure

1. `localparam` with explicit width for state encoding.
2. Combinational block: next-state decode + output, defaults at top.
3. Sequential block: state register + reset.
4. Latch signals that must persist across states (e.g. `is_last`, `count_reg`)
   are updated inside the same `always @(posedge clk)` block using
   `if (state_reg == X && condition) signal_reg <= value` — never in a
   separate always block.

```verilog
localparam [1:0] STATE_IDLE = 2'd0, STATE_WORK = 2'd1, STATE_DONE = 2'd2;
reg [1:0] state_reg = STATE_IDLE, state_next;
```

## 9. Output Ports

`output wire` + internal `_reg` + `assign`. **MUST NOT** use `output reg`.

## 10. Case Statements

- `default` branch **required**.
- No `casex`, `full_case`, or `parallel_case`.

## 11. Module Instantiation

Named port connections only. Each on its own line.

## 12. Number Literals

Always explicit widths: `4'd4`, `8'h2a`, `1'b0`.
Use `{WIDTH{1'b0}}` for parameterized zero.

## 13. Handshake

- `hold_until_ack`: valid stays HIGH until ack.
- `single_cycle`: valid HIGH for exactly one cycle.
- **Back-pressure (`ready`) must be combinational output**: `assign ready = !fifo_full;`
  — never `reg ready` with NBA delay. The upstream source must see the current state
  in the same cycle. `valid` may be registered (spec-driven), but `ready` must not.

## 14. Memory Arrays

Declare: `reg [DATA_WIDTH-1:0] mem[(2**ADDR_WIDTH)-1:0]`.
Terminal condition: `< DEPTH`. Prefer index masking.

## 15. ABSOLUTE BANS

| FORBIDDEN | Use instead |
|-----------|------------|
| SystemVerilog (`logic`, `always_ff`, `always_comb`, `enum`, `struct`) | `wire`/`reg`, `always @*`/`always @(posedge)`, `localparam` |
| `casex` | `case` or `casez` with `?` |
| `defparam` | named port connections |
| `output reg` | `output wire` + `_reg` |
| Blocking `=` in `always @(posedge clk)` | Non-blocking `<=` |
| Two always blocks driving the same `reg` | All register logic in one `always @(posedge clk)` block |
| `#delay` in synthesizable code | Remove |
| Asynchronous/active-low reset | Synchronous `rst` |
| Latches | Flip-flops with defaults |

## 16. Datapath Pipeline Registers

When spec.json specifies `pipeline_stages > 1` or `pipeline_delay_cycles > 1`,
the combinational datapath MUST be broken into registered stages. A fully
combinational chain from input to a single output register violates the timing
contract if `pipeline_stages` indicates intermediate registers are expected.

**Rule**: Between any two `always @(posedge clk)` registers, the combinational
logic depth MUST NOT exceed 12 LUT levels. If it does, insert an intermediate
pipeline register.

**Common pattern — parallel multiplier + adder tree**:
  Stage 1: input registers (data sampling, line buffer, window)
  Stage 2: multiplier output registers (**CRITICAL** — do NOT skip)
  Stage 3: adder tree → output register

```verilog
// Stage 2: multiplier pipeline registers
reg signed [16:0] prod_reg [0:8];
reg             prod_valid_reg;
always @(posedge clk) begin
    if (rst) begin
        prod_valid_reg <= 1'b0;
        for (i = 0; i < 9; i = i + 1)
            prod_reg[i] <= 17'sd0;
    end else if (mac_en) begin
        prod_valid_reg <= 1'b1;
        prod_reg[0] <= prod_0;  // ... prod_reg[8] <= prod_8;
    end else begin
        prod_valid_reg <= 1'b0;
    end
end

// Stage 3: adder tree (combinational from prod_reg)
wire signed [19:0] mac_result = prod_reg[0] + ... + prod_reg[8];
```

**Key**: `valid` and `data` MUST travel through the same number of pipeline
stages, otherwise they drift apart (see Mini-pattern C in vf-coder.md).

## 17. Division and Modulo in Synthesizable Code

AVOID `/` and `%` operators in synthesizable code unless the divisor is a
compile-time constant. Synthesis tools infer full divider circuits for
variable divisors, which are expensive and slow.

| Divisor type | Safe pattern |
|---|---|
| Power of 2 constant | `value >> N` or `value[N-1:0]` |
| Small constant with known range | Expand to conditional: `if (stride == 2) bit_check else 1` |
| Variable (signal-dependent) | Redesign to avoid division; use lookup or counter |

```verilog
// BAD: variable modulo — infers full divider
if ((out_y % stride_val) == 0) ...

// GOOD: known stride range (1 or 2) — expand conditionally
if (stride_reg == 1'b0 || out_y[0] == 1'b0) ...

// BAD: variable division for bounds check
if ((out_y / stride_val) < out_h) ...

// GOOD: equivalent check without division
if (out_y < out_h * stride_val) ...  // multiply by small constant is cheap
```

## 18. Code Hygiene Before Writing

Before writing the final .v file, verify:

1. **No dead signals**: Every declared `_next` or `_reg` signal must be read
   by at least one other statement. `grep` each signal name in the file.
2. **No stale comments**: Comments must match the code. If code was refactored
   (e.g., a condition flipped, a signal renamed), update the comment or remove it.
3. **No placeholder values**: Remove `{N{1'b0}}` placeholders and half-written
   expressions. Every line must be production-ready.
4. **No redundant counters**: If two counters track the same thing (e.g.,
   `pipe_cnt_next` and `pipe_cycle_reg`), keep only one.

## 19. Rotating Line Buffer Depth

When partitioning a streaming window extractor into rotating line buffers, the
number of physical buffers must be large enough that a row is **never overwritten
while still being read** for window assembly.

**Principle**: For a K×K window with P rows of padding on the top edge, a given
image row R is read for the last time when the output reaches row `R + (K-1)/2`.
The next row that maps to the same physical buffer is row `R + NUM_BUFS`.
Conflict occurs when `(R + NUM_BUFS) * WIDTH  ≤  (R + (K-1)/2 + ... ) * WIDTH — ...` .

Rather than memorizing numbers, **derive the minimum buffer count from the read
lifespan vs. write schedule**:

1. Determine when row R is last read (depends on window size, padding, output stride)
2. Determine when row `R + NUM_BUFS` is first written (depends on input rate)
3. Require: `first_write_cycle(R + NUM_BUFS)  >  last_read_cycle(R)`

If the design uses a **streaming fill-then-flush** FSM (all rows buffered before
output begins), the same analysis applies to the flush phase.

**Common cases** (derived from the analysis above, for reference):
- K=3, valid-only output (no padding): 3 buffers suffice for any HEIGHT
- K=3, full-padding (output size = input size): 4 buffers required for HEIGHT ≥ 4

Use `buf_idx = row % NUM_BUFS`. When NUM_BUFS is a power of 2, `row[$clog2(NUM_BUFS)-1:0]` works.

## 20. Cross-Module Timing (from spec.json timing_contract)

When translating from golden_model.py + spec.json:
- Input port with `pipeline_delay_cycles > 0` → caller provides registered output → `input wire`
- Input port with `same_cycle_visible=true` → combinational → `input wire`
- Internal combinational signal → `wire` + `assign` or `always @*`
- Internal register (holds state across cycles) → `reg` + `always @(posedge clk) <=`
- Co-asserted enables: independent `if` blocks, NOT `if/else if`
- Finalize states: read `_reg` only, never `_next` combinational wires
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall