Skip to content

feat: add dict-style hierarchy access and ambient clock domains - #22

Merged
cxzzzz merged 9 commits into
mainfrom
feature/clock-domain
Sep 17, 2026
Merged

cxzzzz merged 9 commits into
mainfrom
feature/clock-domain

Conversation

@cxzzzz

@cxzzzz cxzzzz commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Summary

Two related additions to how signals are located and loaded.

Dict-style hierarchy access

reader[path] returns the Signal or Scope at an exact path; nested
lookups (scope["a.b"]) resolve relative paths, and sig[7:4] bit-selects
like Waveform indexing.

signal = reader['tb.dut.data']
scope = reader['tb.dut']
low_byte = reader['tb.dut.data'][7:0]

Ambient clock domains

ClockDomain bundles a clock signal with a sampling recipe (edge, time or
cycle window), so it doesn't need to be repeated on every call:

with r.clock_domain(clock='tb.clk'):
    w_ptr = r['tb.dut.w_ptr'].w              # Signal.w — ambient shorthand
    r_ptr = r.load_waveform('tb.dut.r_ptr')  # clock omitted — same ambient domain
  • Signal.w / Signal.m / Signal.waveform() / Signal.unknown_mask() read the ambient domain.
  • load_waveform, load_unknown_mask, load_matched_waveforms, and load_matched_unknown_masks default clock/clock_path to None and fall back to the same ambient domain when omitted.

Docs

Rewrote the reader, signal-query, and waveform-analysis guides (EN + ZH) to lead with dict-style access and ambient clock domains, and added ClockDomain to the API reference.

Examples

Rewrote the six existing examples to use dict-style access and ambient clock domains throughout, and added a new multi_cluster_occupancy example demonstrating batch scope matching (get_matched_scopes with brace, recursive wildcard, and regex captures combined) across a bank of clusters.

Testing

Tests, lint, type-check, and doc build all pass, including the FSDB suite.

@cxzzzz
cxzzzz merged commit 171f6a1 into main Sep 17, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant