waveform

name	waveform
description	Use waveform-mcp tools to analyze VCD/FST waveforms and inspect Buckyball signal timing. Use this skill for cycle-level timing analysis, handshake debugging, FSM transition checks, or whenever waveform-level evidence is needed.

Tool Overview

The project uses waveform-mcp with these tools:

• open_waveform(file_path) - open a VCD/FST file
• list_signals(waveform_id, hierarchy_prefix?, name_pattern?, recursive?) - list signals
• read_signal(waveform_id, signal_path, time_index|time_indices) - read signal values
• get_signal_info(waveform_id, signal_path) - get signal metadata
• find_signal_events(waveform_id, signal_path, start?, end?, limit?) - find signal transitions
• find_conditional_events(waveform_id, condition, start?, end?, limit?) - search by condition
• close_waveform(waveform_id) - close waveform

Waveform File Locations

Waveforms generated by simulation are usually in:

• arch/log/<timestamp>/
• format: .vcd or .fst
• use find arch/log -name "*.vcd" -o -name "*.fst" | head -5 to locate files

Signal Hierarchy

Typical Buckyball signal hierarchy:

TOP
├── BuckyballToy (top)
│   ├── bbtile (BBTile)
│   │   ├── buckyball (Buckyball core)
│   │   │   ├── frontend
│   │   │   │   ├── globalDecoder
│   │   │   │   └── globalROB
│   │   │   ├── ballDomain
│   │   │   │   └── bbus (BBus)
│   │   │   │       ├── cmdRouter
│   │   │   │       ├── pmc (BallCyclePMC)
│   │   │   │       ├── balls_0 (first Ball, sorted by ballId)
│   │   │   │       ├── balls_1
│   │   │   │       └── ...
│   │   │   └── memDomain
│   │   │       ├── memFrontend
│   │   │       └── memBackend

Locating Ball Signals

To locate signals for a specific Ball:

1. list_signals(waveform_id, recursive=false) - inspect top level first
2. Drill down with hierarchy prefixes, for example hierarchy_prefix="TOP.BuckyballToy"
3. Or search directly by pattern: list_signals(waveform_id, name_pattern="relu", recursive=true)

Common Check Templates

1. Handshake check (Decoupled valid/ready)

Check whether cmdReq handshakes succeed:

find_conditional_events(waveform_id,
  condition="TOP...cmdReq_valid && TOP...cmdReq_ready")

Check cmdResp handshakes:

find_conditional_events(waveform_id,
  condition="TOP...cmdResp_valid && TOP...cmdResp_ready")

2. SRAM read timing check

Verify 1-cycle SRAM read latency:

# Find read request events
find_conditional_events(waveform_id,
  condition="TOP...bankRead_0_io_req_valid && TOP...bankRead_0_io_req_ready")

# Check `resp.valid` in the next cycle
# Use time_index + 1 from request events
read_signal(waveform_id, "TOP...bankRead_0_io_resp_valid", time_index=<req_time+1>)

3. FSM transition trace

Find all transitions of the state register:

find_signal_events(waveform_id, signal_path="TOP...state")

Then read values at each transition point to reconstruct state evolution.

4. Ball operation latency measurement

Measure cycles from cmdReq.fire to cmdResp.fire:

# Find cmdReq handshake timestamps
req_events = find_conditional_events(waveform_id,
  condition="TOP...cmdReq_valid && TOP...cmdReq_ready")

# Find cmdResp handshake timestamps
resp_events = find_conditional_events(waveform_id,
  condition="TOP...cmdResp_valid && TOP...cmdResp_ready")

# Matching resp_time - req_time gives latency

5. Bank address/data check

Read SRAM read/write addresses and data at a specific time:

read_signal(waveform_id, "TOP...bankRead_0_io_req_bits_addr", time_index=T)
read_signal(waveform_id, "TOP...bankRead_0_io_resp_bits_data", time_index=T+1)
read_signal(waveform_id, "TOP...bankWrite_0_io_req_bits_addr", time_index=T)
read_signal(waveform_id, "TOP...bankWrite_0_io_req_bits_data", time_index=T)

Conditional Search Syntax

find_conditional_events conditions support:

• signal paths: TOP.module.signal
• bitwise operators: ~(NOT), &(AND), |(OR), ^(XOR)
• boolean operators: &&, ||, !
• comparisons: ==, !=
• bit slicing: signal[bit] or signal[msb:lsb]
• previous value: $past(signal) - value at previous time_index
• Verilog literals: 4'b0001, 8'hFF

Common patterns:

• rising edge: !$past(TOP.signal) && TOP.signal
• falling edge: $past(TOP.signal) && !TOP.signal
• handshake: TOP.valid && TOP.ready
• specific bit set: TOP.flags & 4'b0001

Usage Tips

1. List before read - signal names may differ from Chisel source due to name mangling
2. Prefer conditional search over cycle-by-cycle reads - much faster
3. Set reasonable limits - waveforms can be very long
4. Close waveform when done - release memory