Skip to content

Add hci_transaction_tracer and the hci-tracer comparison utility - #84

Merged
FrancescoConti merged 2 commits into
masterfrom
fc/tracer
Jul 30, 2026
Merged

Add hci_transaction_tracer and the hci-tracer comparison utility#84
FrancescoConti merged 2 commits into
masterfrom
fc/tracer

Conversation

@FrancescoConti

Copy link
Copy Markdown
Member

Add a purely passive, simulation-only monitor that observes an HCI-Core stream through the monitor modport of an hci_core_intf interface and appends every transaction to a JSON log file. HCI-Core being bidirectional, two logs are produced, named by the REQ_LOG_FILE and RSP_LOG_FILE parameters: accepted requests (req & gnt) and consumed responses (r_valid & r_ready). Side channels are logged only when their width parameter is non-zero. The body of the module sits inside an ifndef SYNTHESIS guard, so the tracer can be instantiated unconditionally and elaborates to an empty module under synthesis.

Each log is a single well-formed JSON document, closed by a final block, and follows one of the new hci_transaction_request-v1 / hci_transaction_response-v1 JSON schemas in tracer/.

tracer/ also holds hci-tracer, a Rust utility that compares such logs:

hci-tracer hci-vs-hci --a-req F --a-rsp F --b-req F --b-rsp F
hci-tracer hci-req-vs-stream --hci F --stream F
hci-tracer hci-rsp-vs-stream --hci F --stream F
hci-tracer stream-vs-stream --a F --b F

Comparison runs on the content of valid data only, never on the time of a transaction: seq and cycle are reported so a difference can be found in a waveform, but they are structurally excluded from the comparison keys. Byte enables are canonicalized to bit-level masks before being compared, so be and strb encodings with different granularities compare equal when they enable the same data bits, and bytes neither side considers meaningful are don't-care.

The two sequences are aligned with Myers' algorithm, so an inserted transaction is reported as an insertion instead of cascading into a mismatch for every transaction after it. Output is hexadecimal, with only the differing nibbles painted red, a caret row when colour is off, wide values folded into 64-bit rows, and a summary table per section. Logs cut short by an aborted simulation are repaired automatically.

Includes unit tests for every module and integration tests over synthetic logs in tracer/tests/fixtures/, regenerated by gen_fixtures.py.

Add a purely passive, simulation-only monitor that observes an HCI-Core stream
through the `monitor` modport of an `hci_core_intf` interface and appends every
transaction to a JSON log file. HCI-Core being bidirectional, two logs are
produced, named by the `REQ_LOG_FILE` and `RSP_LOG_FILE` parameters: accepted
requests (`req & gnt`) and consumed responses (`r_valid & r_ready`). Side
channels are logged only when their width parameter is non-zero. The body of
the module sits inside an `ifndef SYNTHESIS` guard, so the tracer can be
instantiated unconditionally and elaborates to an empty module under synthesis.

Each log is a single well-formed JSON document, closed by a `final` block, and
follows one of the new `hci_transaction_request-v1` /
`hci_transaction_response-v1` JSON schemas in `tracer/`.

`tracer/` also holds `hci-tracer`, a Rust utility that compares such logs:

  hci-tracer hci-vs-hci        --a-req F --a-rsp F --b-req F --b-rsp F
  hci-tracer hci-req-vs-stream --hci F --stream F
  hci-tracer hci-rsp-vs-stream --hci F --stream F
  hci-tracer stream-vs-stream  --a F --b F

Comparison runs on the content of valid data only, never on the time of a
transaction: `seq` and `cycle` are reported so a difference can be found in a
waveform, but they are structurally excluded from the comparison keys. Byte
enables are canonicalized to bit-level masks before being compared, so `be` and
`strb` encodings with different granularities compare equal when they enable
the same data bits, and bytes neither side considers meaningful are don't-care.

The two sequences are aligned with Myers' algorithm, so an inserted transaction
is reported as an insertion instead of cascading into a mismatch for every
transaction after it. Output is hexadecimal, with only the differing nibbles
painted red, a caret row when colour is off, wide values folded into 64-bit
rows, and a summary table per section. Logs cut short by an aborted simulation
are repaired automatically.

Includes unit tests for every module and integration tests over synthetic logs
in `tracer/tests/fixtures/`, regenerated by `gen_fixtures.py`.
@FrancescoConti

Copy link
Copy Markdown
Member Author

Depends on pulp-platform/hwpe-stream#35

@FrancescoConti
FrancescoConti merged commit d6a4872 into master Jul 30, 2026
2 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