A first investigation in five steps
- See a result before collecting anything. Run the free Console link walkthrough with synthetic evidence.
- Check whether Linux sees the device. Read FPGA missing from lspci if there is no endpoint to select.
- Check what link actually trained. Read XDMA link trained narrow or slow before treating low throughput as a DMA-engine failure.
- Keep address spaces separate. Read the Linux CPU and DMA address explanation, then explore source-linked QDMA fields.
- Inspect a failure you can repeat. Replay the small AXI trace checker and see why a held response matters. This is a different protocol layer from PCIe.
Keep these four layers separate
| Layer | Useful evidence | What it does not establish |
|---|---|---|
| Device visibility and PCIe link | PCI topology, port/endpoint configuration, current and maximum link state | A working application transfer |
| Linux DMA mapping | Driver mapping result, device-visible address, direction and lifetime | That a queue fetched or completed the transfer |
| DMA queue / engine | Correctly matched context and timestamped engine status | Host completion or interrupt delivery |
| AXI interface inside a design | Accepted handshakes, response stability and a trace of the relevant channels | PCIe training or Linux enumeration |
Terms you will see in the tools
- BDF / PCI address
The domain:bus:device.function identifier used to select a PCI function, such as 0000:01:00.0. Attach the full identifier to evidence rather than assuming every logged error belongs to your card. Primary reference.
- Enumeration
The system discovering a PCI device and its resources. A missing endpoint needs upstream-port and topology evidence; an absent device does not provide its own readable configuration capture. Primary reference.
- Configuration space
PCI control, identity and capability data. It is a separate address space from a vendor’s device registers. A configuration dump cannot substitute for a QDMA queue-context dump. Primary reference.
- BAR / register offset
A Base Address Register describes a device resource window. An offset within that window needs the correct BAR, device revision and access method. A field’s bit number alone is not a register address. Primary reference.
- Link width and speed
Width describes active PCIe lanes; speed describes the signaling rate. Compare captured current state with both ends’ capabilities and the intended slot or design. A narrow link is an observation, not a diagnosis of its cause.
- AER
Advanced Error Reporting records PCIe error information. Linux may expose kernel messages and counters. A report can identify a class of error; it does not automatically identify the faulty component or the original cause. Primary reference.
- DMA
Direct Memory Access lets a device transfer data to or from memory. Device-visible DMA addresses can differ from CPU physical addresses, so a CPU pointer is not a safe substitute. Primary reference.
- IOMMU
Hardware that can translate device-visible addresses to physical memory. A captured DMA address alone does not establish the mapping, its permissions or its lifetime. Primary reference.
- DMA mapping
The driver’s arrangement for device access to a buffer. The returned DMA address, direction, length and mapping lifetime belong with a transfer investigation. Primary reference.
- MMIO
Memory-mapped I/O exposes device resources in an address space used by the driver. Reading a register and accessing a RAM buffer are different operations with different semantics. Primary reference.
- QDMA queue context
Per-queue state defined by the applicable IP configuration. Spec Lab supports selected fields in one 256-bit PG302 v4.0 H2C internal-MM software descriptor context. Its bit positions are not BAR offsets. Primary reference.
- READY / VALID handshake
An AXI transfer is accepted at a sampled edge with READY and VALID both asserted. Count accepted edges rather than the number of cycles VALID stays high. Primary reference.
- Backpressure
A receiver delays acceptance by leaving READY low. An offered AXI response must retain VALID and its response data while waiting for acceptance. Primary reference.
- AW, W and B channels
AW carries write-address traffic; W carries write data; B carries the write response. Address and data may arrive separately. A response needs both required earlier handshakes. Primary reference.
- Baseline
A capture you intentionally choose as the comparison reference. It needs compatible device, queue, source revision and conditions. “Baseline” is your provenance claim, not an automated certificate of working hardware.
- Unknown / not captured
Evidence that was not supplied or cannot be decoded in the selected scope. Unknown is not zero, clean, healthy or a confirmed fault. Header7F keeps those states distinct.
- PDF draft / reviewed map
A PDF draft contains heuristic candidate rows that need source review. A decoder map also requires explicit device applicability, address-space meaning and validated field locations. Reviewing a PDF draft does not silently enable a decoder.
Before sharing a result
Keep the device and queue identity, capture time, applicable source revision and missing evidence attached. Review private names and addresses in exports. See local processing and offline scope.