# Header7F selected AXI4-Lite trace checks

This is runnable, inspectable code and an executed synthetic protocol monitor.
It is not RTL simulation, physical hardware validation, a customer case, or a
complete AXI compliance suite. The input samples were hand-authored to inject
specific faults. The reports, VCD files and waveforms are computed from those
samples by the same checker available to download.

## Run from the source tree

Requires Node.js 22 or newer. No packages, network connection, simulator, account
or hardware are needed. Output files are written only when --out is supplied.

    node examples/axi-lite/check-trace.mjs examples/axi-lite/held-response-pass.trace.json --out output/pass
    node examples/axi-lite/check-trace.mjs examples/axi-lite/drop-bvalid-fail.trace.json --out output/fail

The first command exits 0. The deliberately faulty case exits 1; this is the
expected result, so do not join the commands with && when running both.
Use --help for the interface. Exit 2 means invalid input. CSV with the exact
header below is also accepted (decimal integers, no quoted fields):

    cycle,ARESETn,AWVALID,AWREADY,WVALID,WREADY,BVALID,BREADY,BRESP

For the website downloads, put axi-lite-check-trace.mjs beside a downloaded
axi-*.trace.json (or CSV), then run, for example:

    node axi-lite-check-trace.mjs axi-drop-bvalid-fail.trace.json --out output/fail

Outputs are report.json, report.md, trace.vcd and waveform.svg. SVG previews
support at most 64 samples; reports and VCD support up to 10,000. Input is limited
to 1 MiB. The VCD clock is a rendering clock with a 10 ns period, not a measured
hardware clock. Values are set before the illustrated rising edge.

## Exactly what is checked

1. H7F_AXI_BVALID_HOLD: after a sampled BVALID=1/BREADY=0, the next non-reset
   edge must still have BVALID=1, including an edge where BREADY becomes 1.
2. H7F_AXI_BRESP_HOLD: BRESP stays unchanged across that same stalled response.
3. H7F_AXI_B_AFTER_AW_W: BVALID needs one earlier unmatched AW handshake and one
   earlier unmatched W handshake. AW and W are independent; either may arrive
   first. Accepting them on the current edge does not authorize an already
   asserted BVALID on that edge.

The monitor tracks counts since observed reset. Inputs must start at cycle 0
with ARESETn=0 and contain every consecutive ACLK rising-edge sample. Signals
are known integer 0/1 values (BRESP is 0..3); X/Z and missing edges are rejected.
Reset clears the tracked transactions and hold obligation. A pending response
at trace end is reported as unresolved, not a violation or a successful transfer.

AMD PG101 v2.0, checks 35, 34 and 32 respectively, documents these conditions:
https://docs.amd.com/r/en-US/pg101-axi-protocol-checker/AXI-Protocol-Checks-and-Descriptions

The underlying Arm AXI/ACE protocol specification is IHI 0022H:
https://developer.arm.com/documentation/ihi0022/h/

## Expected results

- held-response-pass: AW accepted at cycle 2, W at 4, B held at 5 and 6,
  accepted at 7. No violation in these three checks.
- data-before-address-pass: W at cycle 2, AW at 4; the same valid response.
- drop-bvalid-fail: BVALID drops at cycle 6 after a stalled response at 5.
  H7F_AXI_BVALID_HOLD is reported.
- change-bresp-fail: BRESP changes from OKAY (0) to SLVERR (2) at cycle 6
  while the response is unaccepted. H7F_AXI_BRESP_HOLD is reported.
- early-response-fail: BVALID is asserted at cycle 3, before W acceptance at 4.
  H7F_AXI_B_AFTER_AW_W is reported.

## Limits and integration

A finite passive waveform cannot prove that VALID generation is independent
of READY. Source inspection, directed stimulus and/or formal properties are
needed for that design dependency. This monitor does not check deadlock,
response deadlines, read channels, AW/W payload stability, reset timing,
register behavior, CDC, or device function. A passing result means only that
these three selected checks found no violation in the supplied samples.

write-response-assertions.sv contains optional SystemVerilog assertion examples
for integration. No iverilog, Verilator or commercial simulator was available
for this run, so the SVA snippets are not compile-checked or qualified on any
simulator. Adapt counters and reset assumptions to your environment. No Questa,
VCS, Xcelium, xsim, UVM or complete AXI verification support is advertised.

Reproduce the published artifacts from the repository root:

    node scripts/generate-axi-evidence.mjs
    node --test tests/axi-trace.test.mjs

The deterministic generator checks the expected verdict and rule for every
fixture before publishing the derived files. It records input SHA-256 hashes
and engine version in axi-trace-report.json. These hashes support reproduction;
they are not signatures, provenance attestations or hardware-validation claims.

License: MIT. See LICENSE / axi-lite-LICENSE.txt. Third-party specifications
retain their respective terms and are linked, not redistributed.
