CLI reference¶
This page contains the detailed help from the version-matched wavepeek binary.
wavepeek¶
wavepeek queries saved RTL waveform dumps.
Behavior:
- Each waveform command opens one waveform dump, runs one query, writes its output, and exits.
- Every build supports VCD and FST. FSDB requires Linux x86_64, Cargo feature `fsdb`, and the Synopsys Verdi FSDB Reader SDK.
- Waveform commands write text by default. Use `--json` for one JSON value or `--jsonl` for a stream of JSON records.
- Time values use an integer and an explicit unit, for example `250ps`, `10ns`, or `2us`. Supported units are `zs`, `as`, `fs`, `ps`, `ns`, `us`, `ms`, and `s`.
Examples:
wavepeek info --waves dump.fst
wavepeek scope --waves dump.fst --tree --max-depth 2
wavepeek help extract axi
Notes:
- Count and traversal limits keep output bounded by default. Use `unlimited` only when the full result is needed.
- Parsed times use the dump's `time_unit`. The `--from` and `--to` boundaries are inclusive.
- Text failures use `fatal: <category>: <message>`. JSON and JSONL use typed fatal records.
- Names ending in `.md` refer to files in the packaged skill. Run `wavepeek skill ./wavepeek-skill` to extract it, then open the files under `./wavepeek-skill/references/`.
- See machine-output.md for machine output and timeunits.md for time syntax.
Usage: wavepeek [OPTIONS] [COMMAND]
Waveform commands:
info Show metadata for one waveform dump.
scope List scopes in a waveform hierarchy.
signal List signals in one waveform scope.
value Read selected signal values at one or more times.
change Read signal values at selected events over a time range.
property Evaluate a Boolean expression at selected events.
extract Extract event rows from waveform signals.
Helper commands:
skill Extract the packaged agent skill into a directory.
help Show detailed help for a command path.
Options:
-V
Print semver version
--version
Print full version
-h, --help
Print help (see a summary with '-h')
Optional features:
- FSDB - disabled (FSDB support is currently Linux x86_64 only; reinstall with Cargo flag `--features fsdb` and provide the Synopsys Verdi FSDB Reader SDK)
wavepeek info¶
Show metadata for one waveform dump.
Behavior:
- Reports the dump time unit, start time, and end time.
- Text output uses a simple field list. JSON and JSONL use the standard machine output records.
Example:
wavepeek info --waves dump.fst
Notes:
- Run `info` before choosing values for `--at`, `--from`, or `--to`.
- See explore-dump.md for the usual inspection flow and timeunits.md for time rules.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek info [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
Output options:
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek scope¶
List scopes in a waveform hierarchy.
Behavior:
- Matches `--filter` against full scope paths and reports each scope's name, depth, and kind.
- Uses stable pre-order depth-first traversal with lexicographic child ordering.
- Reports normalized scope kinds for modules and other recorded hierarchy objects.
- `--tree` prints an indented hierarchy and includes the ancestors of matching scopes.
- Truncation produces a coded diagnostic. An empty text result prints a short message unless `--summary` is set.
Examples:
wavepeek scope --waves dump.fst --tree --max-depth 2 --max 30
wavepeek scope --waves dump.fst --filter '.*(cpu|axi|uart).*'
Notes:
- Use `scope` before commands that need an exact scope path.
- See explore-dump.md for a hierarchy walkthrough and paths.md for path rules.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek scope [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
Selection options:
--max-depth <MAX_DEPTH>
Maximum traversal depth (`unlimited` disables depth truncation)
[default: 5]
--filter <FILTER>
Regex filter for full scope path
[default: .*]
Output options:
--max <MAX>
Maximum number of matching scopes (tree ancestors do not count; `unlimited` disables truncation)
[default: 50]
--tree
Render hierarchy as an indented tree
--summary
Suppress result rows while retaining context and completeness metadata
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek signal¶
List signals in one waveform scope.
Behavior:
- Matches `--filter` against signal names and reports each signal's name, kind, and available metadata such as width.
- Lists direct signals by default. `--recursive` also visits child scopes in stable depth-first order.
- Reports normalized signal kinds for wires and other recorded objects.
- Omits ambiguous FSDB paths instead of choosing a backing record and produces a coded diagnostic.
- Truncation produces a coded diagnostic. An empty text result prints a short message unless `--summary` is set.
Examples:
wavepeek signal --waves dump.fst \
--scope tb.dut.cpu \
--filter '.*(clk|reset|state).*'
wavepeek signal --waves dump.fst \
--scope tb.dut --recursive --max-depth 2 --abs
Notes:
- Use `--abs` to print canonical paths that can be copied into later commands.
- See explore-dump.md for signal discovery and paths.md for path rules.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek signal [OPTIONS] --waves <FILE> --scope <SCOPE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--scope <SCOPE>
Exact scope path (for example, top.cpu)
Output options:
--max <MAX>
Maximum number of entries (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Show canonical signal paths
--summary
Suppress result rows while retaining context and completeness metadata
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Selection options:
--filter <FILTER>
Regex filter for signal name
[default: .*]
--recursive
Recursively include nested child scopes
--max-depth <MAX_DEPTH>
Maximum recursion depth below --scope; requires --recursive (`unlimited` disables this limit)
[default: 5]
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek value¶
Read selected signal values at one or more times.
Behavior:
- `--at` and `--signals` accept comma-separated values, repeated options, or both. The command prints one row per `--at` value and preserves request order and duplicates.
- Uses canonical signal paths by default. With `--scope`, names may be relative or canonical paths inside that scope, and both forms may be mixed.
- A trailing `[msb:lsb]` selects bits from a flat integral signal. Use `[n:n]` for one bit; `[n]` remains part of an ordinary waveform path.
- Exact waveform paths take precedence over projection syntax.
- Text values use Verilog literals such as `8'h0f`, including `x` and `z` digits.
- The command fails if a signal cannot be resolved or a requested time is finer than the dump resolution.
Examples:
wavepeek value --waves dump.fst \
--scope tb.dut.cpu --at 120ns --signals state,pc
wavepeek value --waves dump.fst \
--at 100ns,110ns --signals 'top.status[7:4]'
Notes:
- Time values need explicit units and must align with dump precision.
- To reproduce a `change` or `property` row, pass its `sample_time` to `--at`. In `pre-edge` mode, `time` is the trigger time and `sample_time` is the value sample time.
- See inspect-values.md for examples, paths.md for signal names, and timeunits.md for time rules.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek value [OPTIONS] --waves <FILE> --at <AT> --signals <SIGNALS>...
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
Selection options:
--at <AT>
Time points with explicit units, comma-separated or repeated (for example, 1337ns or 10ns,20ns)
--scope <SCOPE>
Scope for relative signal names (for example, top.cpu)
--signals <SIGNALS>...
Signal paths or flat projections, comma-separated or repeated (for example, state,pc or status[7:4])
Output options:
--abs
Show canonical signal paths
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek change¶
Read signal values at selected events over a time range.
Behavior:
- `--on` selects events, and `--signals` selects the values printed for each event. `--signals` accepts comma-separated values, repeated options, or both.
- Signal names may end in `[msb:lsb]`. Sparse rows, delta rows, and wildcard comparisons use the projected values. Exact waveform paths take precedence, and `[n]` remains path syntax.
- `--row-mode dense` prints every sampled event. `sparse` prints only samples that changed from the previous selected sample.
- `--row-values full` prints every requested value. `delta` prints changed values, except that its first row is always full.
- Pre-edge sampling reads values before edge-only triggers while keeping the trigger timestamp as the row time. Events without an earlier representable sample are skipped.
- Native sampling reads values at the event timestamp and is required for wildcard triggers such as `--on '*'`.
- Range boundaries are inclusive. In sparse mode, `--from` provides the comparison baseline and does not force a row.
- Truncation produces a coded diagnostic. An empty text result prints a short message unless `--summary` is set.
Examples:
wavepeek change --waves dump.fst \
--scope tb.dut.cpu --on 'posedge clk' \
--signals state,req,ack
wavepeek change --waves dump.fst \
--from 100ns --to 160ns --on '*' --sample-mode native \
--signals top.req,top.ack
Notes:
- JSON and JSONL rows contain `time` for the selected event and `sample_time` for the sampled values. Text shows `sample@<time>` only when they differ.
- See inspect-values.md for common queries, sampling.md for sampling modes, and event-expressions.md for `--on` syntax.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek change [OPTIONS] --waves <FILE> --signals <SIGNALS>... --on <ON>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
Selection options:
--from <FROM>
Start of the inclusive time range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive time range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative signal and trigger names (for example, top.cpu)
--signals <SIGNALS>...
Signal paths or flat projections, comma-separated or repeated (for example, state,req or status[7:4])
--on <ON>
Event trigger expression (for example, 'posedge clk'; use `*` only with `--sample-mode native`)
--sample-mode <MODE>
Value sampling mode for event-selected rows
[default: pre-edge]
[possible values: native, pre-edge]
Output options:
--row-mode <MODE>
Select whether every sampled event or only changed samples become rows
[default: dense]
[possible values: dense, sparse]
--row-values <VALUES>
Select whether rows contain all values or only changed values
[default: full]
[possible values: full, delta]
--max <MAX>
Maximum number of snapshot rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Print canonical paths
--summary
Suppress result rows while retaining context and completeness metadata
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek property¶
Evaluate a Boolean expression at selected events.
Behavior:
- `--on` selects events, and `--eval` defines the expression checked at each event.
- `--capture match` prints every selected event where the expression is true.
- `--capture switch` prints both result transitions. `assert` prints false-to-true transitions, and `deassert` prints true-to-false transitions.
- Pre-edge sampling checks the expression before edge-only triggers while keeping the trigger timestamp as the row time.
- Native sampling checks at the event timestamp and is required for wildcard triggers such as `--on '*'`.
- Truncation produces a coded diagnostic. An empty text result prints a short message unless `--summary` is set.
Examples:
wavepeek property --waves dump.fst \
--scope tb.dut --on 'posedge clk' \
--eval 'req && !ack'
wavepeek property --waves dump.fst \
--on '*' --sample-mode native \
--eval "top.error != 8'h00" --capture assert
Notes:
- This is a sampled Boolean check, not a SystemVerilog temporal assertion.
- JSON and JSONL rows contain `time` for the selected event and `sample_time` for the expression sample. Text shows `sample@<time>` only when they differ.
- See evaluate-properties.md for common queries, boolean-expressions.md for `--eval`, and sampling.md for sampling modes.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek property [OPTIONS] --waves <FILE> --on <ON> --eval <EVAL>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
Selection options:
--from <FROM>
Start of the inclusive time range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive time range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative event and expression names (for example, top.cpu)
--on <ON>
Event trigger expression (for example, 'posedge clk'; use `*` only with `--sample-mode native`)
--sample-mode <MODE>
Value sampling mode for event-selected rows
[default: pre-edge]
[possible values: native, pre-edge]
--eval <EVAL>
Logical expression evaluated at selected events (for example, 'ready && !stall')
Output options:
--capture <MODE>
Capture mode: level (`match`) or edge (`switch`, `assert`, `deassert`)
[default: switch]
[possible values: match, switch, assert, deassert]
--max <MAX>
Maximum number of property rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--summary
Suppress result rows while retaining context and completeness metadata
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract¶
Extract event rows from waveform signals.
Behavior:
- `generic` selects clocked events with an event expression and Boolean predicate, then samples an ordered payload.
- Protocol extractors map standard interface signals and emit protocol-specific channel or phase events.
Examples:
wavepeek extract generic --waves dump.fst \
--scope top.fifo --on 'posedge clk' \
--when 'valid && ready' --payload data
wavepeek extract axi --waves dump.fst \
--scope top.axi --profile axi4 \
--map aclk=clk --include '^m_axi_'
Notes:
- Extractors report sampled events. They do not perform full protocol checking or reconstruct high-level transactions.
- See extract-transfers.md for generic extraction and extract-axi.md, extract-axis.md, extract-ahb.md, extract-apb.md, or extract-atb.md for AMBA examples.
Usage: wavepeek extract <COMMAND>
Commands:
ahb Extract manager-facing AHB address and data-phase events.
apb Extract APB Setup and Access events.
atb Extract ATB transfer, flush, and synchronization-request events.
axi Extract AXI-family ready/valid channel transfers.
axistream Extract AXI-Stream transfers.
generic Extract custom synchronous events and their payload values.
help Show detailed help for a command path.
Options:
-h, --help
Print help (see a summary with '-h')
wavepeek extract ahb¶
Extract manager-facing AHB address and data-phase events.
Behavior:
- Supports AHB-Lite and AHB5 from Arm IHI 0033C, Issue C.
- Tracks one accepted address phase so data completions remain separate from idle clocks.
- Emits address, data-complete, reset, and desynchronized events by default. The include flags add stall, idle, or busy cycle events.
- Samples control and payload one dump tick before each rising HCLK edge.
- Uses manager-facing HREADY. HREADYOUT, HSELx, and parity or check signals are outside this interface.
- Explicit `STD_NAME=WAVES_NAME` mappings override signals found by include regexes.
- A source file can provide the profile, output name, include flags, regexes, and mappings.
Example:
wavepeek extract ahb --waves dump.fst \
--scope tb.dut.ahb_m --profile ahb-lite \
--map hclk=clk --include '^m_ahb_'
Notes:
- `--source` conflicts with `--profile`, `--name`, `--map`, `--include`, `--include-stall`, `--include-idle`, and `--include-busy`.
- Pipeline warm-up starts before `--from`, so an in-range completion may belong to an earlier address phase. JSON field `initial_data_phase` records that state.
- JSON context includes the Issue C profile, resolved mappings, and ordered event rows.
- The extractor does not reconstruct bursts, combine transactions, or join address and data phases.
- See extract-ahb.md for mapping and stall examples. See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract ahb [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--profile <PROFILE>
AHB profile from Arm IHI 0033C
[default: ahb-lite]
[possible values: ahb-lite, ahb5]
--source <FILE>
JSON AHB source file with profile, include flags, name, regexes, and mappings (for example, ahb-source.json)
--name <NAME>
Interface name stored in output metadata (default: ahb)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative AHB signal names and include regexes (for example, top.ahb_m)
Signal mapping options:
--map <STD=WAVES>
Explicit AHB signal mapping; may be repeated (for example, haddr=dmem_haddr)
--include <REGEX>
Regex for AHB auto-mapping candidates; may be repeated (for example, '^m_ahb_')
Event options:
--include-stall
Emit one data-stall event for each active low-HREADY cycle
--include-idle
Emit one idle event for each known-ready IDLE slot
--include-busy
Emit one busy event for each known-ready BUSY slot
Output options:
--max <MAX>
Maximum number of public AHB event rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--summary
Suppress result rows while retaining context and completeness metadata
--abs
Print canonical mapping paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract apb¶
Extract APB Setup and Access events.
Behavior:
- Supports APB3, APB4, and APB5 from Arm IHI 0024E.
- Emits setup and access-complete rows by default. `--include-wait` adds one row for each waited Access cycle.
- Mapped PREADY mode requires `pready`. Implicit-high mode forbids `pready` and wait rows.
- Maps one concrete Completer PSELx signal as `psel`.
- Samples reset, predicates, direction, and payload at the pre-edge sample point.
- Explicit `STD_NAME=WAVES_NAME` mappings override signals found by include regexes.
- A source file can provide the profile, PREADY mode, wait flag, output name, regexes, and mappings. Source files use canonical lowercase profile and mode values.
Example:
wavepeek extract apb --waves dump.fst \
--scope tb.dut.uart_apb --profile apb4 \
--map pclk=clk --include '^uart_'
Notes:
- `--source` conflicts with `--profile`, `--pready-mode`, `--include-wait`, `--name`, `--map`, and `--include`.
- JSON context includes APB metadata, resolved mappings, and event rows.
- Rows are independent sampled events. The extractor does not correlate or validate transactions.
- See extract-apb.md for mapping and wait-state examples. See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract apb [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--profile <PROFILE>
APB profile from Arm IHI 0024E
[default: apb4]
[possible values: apb3, apb4, apb5]
--pready-mode <MODE>
PREADY handling mode
[default: mapped]
[possible values: mapped, implicit-high]
--include-wait
Emit one access-wait row per waited Access cycle
--source <FILE>
JSON APB source file with profile, PREADY mode, wait flag, name, regexes, and mappings (for example, apb-source.json)
--name <NAME>
Interface name stored in output metadata (default: apb)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative APB signal names and include regexes (for example, top.uart_apb)
Signal mapping options:
--map <STD=WAVES>
Explicit APB signal mapping; may be repeated (for example, psel=uart_psel)
--include <REGEX>
Regex for APB auto-mapping candidates; may be repeated (for example, '^uart_apb_')
Output options:
--max <MAX>
Maximum number of extracted event rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Print canonical mapping and payload paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
--summary
Suppress result rows while retaining context and completeness metadata
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract atb¶
Extract ATB transfer, flush, and synchronization-request events.
Behavior:
- Supports ATB-A, ATB-B, and ATB-C from Arm IHI 0032C, Issue C.
- Builds separate event sources for complete ATVALID/ATREADY and AFVALID/AFREADY handshakes.
- A mapped SYNCREQ signal on ATB-B or ATB-C adds synchronization-request events.
- Samples reset, predicates, and transfer payload at the pre-edge sample point.
- Orders same-edge events as transfer, flush, then synchronization request.
- Preserves mapped ATBYTES, ATDATA, and ATID values without trace decoding.
- Explicit `STD_NAME=WAVES_NAME` mappings override signals found by include regexes.
- A source file can provide the profile, output name, regexes, and mappings. Source files use canonical hyphenated profile names.
Example:
wavepeek extract atb --waves dump.fst \
--scope tb.dut.etm --profile atb-c \
--map atclk=trace_clk --include '^trace_(at|af|sync)'
Notes:
- `--source` conflicts with `--profile`, `--name`, `--map`, and `--include`.
- CLI profile aliases are `atb_a`, `atb_b`, `atb_c`, `atbv1.0`, and `atbv1.1`.
- JSON context includes ATB metadata, resolved mappings, and event rows.
- Rows are stateless sampled events. The extractor does not reconstruct packets, stalls, flush episodes, or synchronization episodes.
- See extract-atb.md for mapping examples. See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract atb [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--profile <PROFILE>
ATB profile from Arm IHI 0032C Issue C
[default: atb-c]
[possible values: atb-a, atb-b, atb-c]
--source <FILE>
JSON ATB source file with profile, name, regexes, and mappings (for example, atb-source.json)
--name <NAME>
Interface name stored in output metadata (default: atb)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative ATB signal names and include regexes (for example, top.etm)
Signal mapping options:
--map <STD=WAVES>
Explicit ATB signal mapping; may be repeated (for example, atvalid=etm_atvalid)
--include <REGEX>
Regex for ATB auto-mapping candidates; may be repeated (for example, '^etm_(at|af)')
Output options:
--max <MAX>
Maximum number of extracted event rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Print canonical mapping and payload paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
--summary
Suppress result rows while retaining context and completeness metadata
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract axi¶
Extract AXI-family ready/valid channel transfers.
Behavior:
- Supports AXI3, AXI4, AXI4-Lite, AXI5, AXI5-Lite, ACE, ACE-Lite, ACE5, ACE5-Lite, ACE5-LiteDVM, and ACE5-LiteACP.
- AXI3, AXI4, AXI4-Lite, ACE, ACE-Lite, and ACE5 use Arm IHI 0022H.c. The remaining profiles use the Arm IHI 0022L ready/valid transport.
- Builds one event source for each complete ready/valid channel. AXI5 and ACE5-LiteDVM can add DVM `ac` and `cr` channels, but not `cd`.
- Samples reset, ready and valid predicates, and payload at the pre-edge sample point.
- Explicit `STD_NAME=WAVES_NAME` mappings override signals found by include regexes.
- A source file can provide the profile, output name, regexes, and mappings. Source files use canonical hyphenated profile names.
Example:
wavepeek extract axi --waves dump.fst \
--scope tb.dut.axi_m --profile axi4 \
--map aclk=clk --include '^m_axi_(aw|w|b|ar|r)'
Notes:
- `--source` conflicts with `--profile`, `--name`, `--map`, and `--include`.
- CLI aliases include `ace5_lite`, `ace5-litedvm`, `ace5_litedvm`, `ace5_lite_dvm`, `ace5-liteacp`, `ace5_liteacp`, and `ace5_lite_acp`.
- JSON context includes AXI metadata, resolved mappings, and transfer rows.
- Rows are raw channel transfers, including eligible `ac` and `cr` transfers. The extractor does not decode DVM messages or coherency state. It does not reconstruct bursts, ordering, or outstanding request state.
- See extract-axi.md for mapping examples. See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract axi [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--profile <PROFILE>
AXI profile from Arm IHI 0022H.c or IHI 0022L
[default: axi4]
[possible values: axi3, axi4, axi4-lite, axi5, axi5-lite, ace, ace-lite, ace5, ace5-lite, ace5-lite-dvm, ace5-lite-acp]
--source <FILE>
JSON AXI source file with profile, name, regexes, and mappings (for example, axi-source.json)
--name <NAME>
Interface name stored in output metadata (default: axi)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative AXI signal names and include regexes (for example, top.axi_m)
Signal mapping options:
--map <STD=WAVES>
Explicit AXI signal mapping; may be repeated (for example, awvalid=cpu_dmem_awvalid)
--include <REGEX>
Regex for AXI auto-mapping candidates; may be repeated (for example, '^axi_(aw|w|b|ar|r)_')
Output options:
--max <MAX>
Maximum number of extracted transfer rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Print canonical mapping and payload paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
--summary
Suppress result rows while retaining context and completeness metadata
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract axistream¶
Extract AXI-Stream transfers.
Behavior:
- Supports AXI4-Stream and AXI5-Stream from Arm IHI 0051B, Issue B.
- Mapped TREADY mode requires `tvalid` and `tready`. Implicit-high mode declares that physical TREADY is absent.
- Samples reset, handshake predicates, and payload at the pre-edge sample point for each rising ACLK edge.
- One invocation maps one stream interface and emits one row per completed transfer without adding a channel name.
- Explicit `STD_NAME=WAVES_NAME` mappings override signals found by include regexes.
- A source file can provide the profile, TREADY mode, output name, regexes, and mappings.
Example:
wavepeek extract axistream --waves dump.fst \
--scope tb.dut.video_out --profile axi4-stream \
--map aclk=clk --include '^video_'
Notes:
- `--source` conflicts with `--profile`, `--tready-mode`, `--name`, `--map`, and `--include`.
- AXI5-Stream wake-up, parity, and check signals are outside this extractor.
- See extract-axis.md for mapping and implicit-high examples. See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract axistream [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--profile <PROFILE>
AXI-Stream profile from Arm IHI 0051B Issue B
[default: axi4-stream]
[possible values: axi4-stream, axi5-stream]
--tready-mode <MODE>
Whether TREADY is mapped or physically omitted and implicitly HIGH
[default: mapped]
[possible values: mapped, implicit-high]
--source <FILE>
JSON AXI-Stream source file with profile, TREADY mode, name, regexes, and mappings (for example, axistream-source.json)
--name <NAME>
Interface name stored in output metadata (default: axistream)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative AXI-Stream signal names and include regexes (for example, top.video_out)
Signal mapping options:
--map <STD=WAVES>
Explicit AXI-Stream signal mapping; may be repeated (for example, tvalid=video_tvalid)
--include <REGEX>
Regex for AXI-Stream auto-mapping candidates; may be repeated (for example, '^video_')
Output options:
--max <MAX>
Maximum number of extracted transfer rows (`unlimited` disables truncation, value must be > 0)
[default: 50]
--abs
Print canonical mapping and payload paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
--summary
Suppress result rows while retaining context and completeness metadata
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek extract generic¶
Extract custom synchronous events and their payload values.
Behavior:
- `--on` selects edge-only events. `--when` and `--payload` are always sampled at the pre-edge sample point.
- `--payload` accepts comma-separated values, repeated options, or both. Entries may end in `[msb:lsb]`, and request order and duplicates are preserved.
- Use `[n:n]` for one bit. Exact waveform paths take precedence, and `[n]` remains path syntax.
- In CLI mode, `--on`, `--when`, and `--payload` define one source named by `--name`.
- A source file can define one or more sources. `--source` conflicts with `--name`, `--on`, `--when`, and `--payload`.
- JSON and JSONL rows include `time`, `sample_time`, `source`, and ordered payload values.
Examples:
wavepeek extract generic --waves dump.fst \
--scope tb.dut.queue --on 'posedge clk' \
--when 'valid && ready' --payload data,last
wavepeek extract generic --waves dump.fst \
--scope tb.dut --source fifo-sources.json
Notes:
- Use a protocol extractor when it already supports the interface.
- See extract-transfers.md for generic extraction examples, boolean-expressions.md for `--when`, and event-expressions.md for `--on`.
- See machine-output.md for JSON and JSONL records.
Usage: wavepeek extract generic [OPTIONS] --waves <FILE>
Input options:
--waves <FILE>
Path to a VCD, FST, or FSDB waveform file (for example, dump.fst)
--source <FILE>
JSON file for multi-source extraction (for example, fifo-sources.json)
Selection options:
--from <FROM>
Start of the inclusive event range (for example, 1234ns; default: dump start)
--to <TO>
End of the inclusive event range (for example, 2000ns; default: dump end)
--scope <SCOPE>
Scope for relative event, predicate, and payload names (for example, top.fifo)
--name <NAME>
Source name for single-source CLI mode (default: transfer)
--on <ON>
Edge-only event expression for single-source CLI mode (for example, 'posedge clk')
--when <WHEN>
Pre-edge predicate for single-source CLI mode (for example, 'valid && ready')
--payload <SIGNAL[,SIGNAL...]>...
Payload paths or flat projections, comma-separated or repeated (for example, data,last or status[7:4])
Output options:
--max <MAX>
Maximum number of extracted rows across all sources (`unlimited` disables truncation, value must be > 0)
[default: 50]
--summary
Suppress result rows while retaining context and completeness metadata
--abs
Print canonical payload paths in human output
--json
Machine-readable JSON output
--jsonl
Stream newline-delimited JSON output
Other options:
-h
Print help (see more with '--help')
--help
Print help (see a summary with '-h')
wavepeek skill¶
Extract the packaged agent skill into a directory.
Behavior:
- Writes the skill package that matches the installed `wavepeek` version.
- Requires a new or empty destination directory.
Example:
wavepeek skill ./wavepeek-skill
Notes:
- Follow your agent harness's instructions to install the extracted directory.
- See quickstart.md for extraction and installation.
Usage: wavepeek skill <DIRECTORY>
Arguments:
<DIRECTORY>
New or empty destination directory (for example, ./wavepeek-skill)
Options:
-h, --help
Print help (see a summary with '-h')
wavepeek help¶
Show detailed help for a command path.
Behavior:
- With no command path, prints top-level help.
- With a command path, prints help for that command or nested subcommand.
Examples:
wavepeek help
wavepeek help value
wavepeek help extract axi
Notes:
- See commands.md for a summary of the command groups.
Usage: wavepeek help [COMMAND]...
Arguments:
[COMMAND]... Command path to describe (for example, extract axi)