MSI-X and Requester Support
This page describes what the generated firmware does for MSI-X and for requests the board starts itself, which boards support each, and the limits you should know before building. Release 0.20.0 added both.
MSI-X serving
If the donor has an MSI-X capability, the firmware serves the donor's own MSI-X table and Pending Bit Array (PBA) from the same BAR the donor uses.
- Table and PBA reads and writes work, including the per-vector mask bits and the function mask.
- Multi-BAR layouts are supported. Many NICs keep registers in one BAR and the MSI-X table in another. For example, the Intel I350 has registers in a 64-bit BAR0 and the table and PBA in BAR3. The firmware serves each at its real BAR index.
- The generator serves at most two BARs: the register BAR and, when it is a different BAR, the MSI-X BAR.
- The table and the PBA must be in the same BAR. A donor with the table and PBA in different BARs, or an MSI-X BIR that does not name an implemented BAR, fails the build.
- BAR sizes and types come from the Stage 1 capture. The generated PCIe IP sets the BAR apertures before the MSI-X BIR, so the BIR never points at a disabled BAR.
MSI-X limits
- No interrupts are generated. Nothing in the generated design raises an interrupt event, so the MSI-X controller never sends a message on its own. The table, PBA and mask registers behave as the donor's do, but the firmware does not produce interrupts.
- Unexplained registers are not emulated. The firmware reproduces register behavior that the capture can explain. Registers the capture cannot explain are not emulated.
- Read-only default. A served BAR with no learned register model is read-only.
--writable-bar-fallbackreplaces that with generic writable RAM that aliases every 4 KiB. That is not donor behavior. - Board coverage. The reset and CDC fixes that go with this work are on CaptainDMA 75T x1, EnigmaX1, PCIeSquirrel, ScreamerM2, GBOX, ZDMA 100T and ac701. They are not ported to CaptainDMA 35T, NeTV2, acorn_ft2232h, pciescreamer or sp605.
Requester tracking
Requester tracking lets the board issue its own memory read requests, follow each one by tag, and report a completion timeout if the answer never arrives.
What it does:
- Replaces the tag of every tracked read request with a tag the FPGA allocates, and restores the host's tag on the completion it hands back. A late completion cannot match a newer request.
- Tracks the completion timeout using the timeout ranges the donor reports in Device Capabilities 2 (DevCap2).
- Supports Completion Timeout Disable through a startup controller that programs the PCIe core's DRP interface while the core is held in reset.
- Refuses a tracked request instead of stalling when no tag is free or too many reads are in flight.
Requests that are refused before they reach the link:
- Reads with a Requester ID that is not the function's live ID, with the TD (digest) bit set, that are malformed, that exceed the Max_Read_Request_Size, or that cross a 4 KB boundary.
- Any read while Bus Master Enable is clear.
- Locked reads, I/O and configuration requests, and atomic operations.
Posted writes, messages and the board's own completion responses pass through unchanged.
Requirements
- Board: CaptainDMA 100T (
pcileech_100t484_x1) only. The requester sources ship with that board project. - Donor data: the capture must include the donor's Extended Tag Field Supported bit. A capture without it fails the build.
- Startup guard. When the donor reports completion timeout ranges A to D, Completion Timeout Disable supported and no Extended Tag support, the build adds a guard that is pinned to the shipped board controller sources. The guard checks:
- Vivado 2026.1;
- the Xilinx 7-series PCIe IP
pcie_7xversion 3.3; - part
xc7a100tfgg484-1and top modulepcileech_100t484_x1_top; - Gen1 x1, 64-bit interface, 62.5 MHz user clock, endpoint port type;
- the SHA-256 of each pinned controller source file.
If any check fails, Vivado stops with an Unqualified requester ... error. Do not edit the board's requester or startup controller sources for a build that uses the guard.
- Host software: the host must run LeechCore 2.23 or newer. See Host software.
FT601 PHY (CaptainDMA 100T)
The CaptainDMA 100T builds an MMCM-clocked FT601 PHY by default. --ft601-legacy-phy selects the older PHY instead. The option is accepted only for boards that have the MMCM PHY, which today is the CaptainDMA 100T. Other boards fail with an error that names the missing source file.
Packet-safe FIFOs and reset
The TX and RX FIFOs reserve space for a whole packet before admitting it, so a packet is not cut in the middle when a FIFO fills. A PCIe reset, abort or drain empties the queues at packet boundaries.
Host software
The COM link between the board and the host relies on LeechCore 2.23 or newer, which understands the packet-start flag the firmware sends (required for FPGA version 4.13 and later). With an older LeechCore:
- After a FIFO overflow, the host can append a leftover partial packet to the next TLP.
- After a COM session abort, a cut packet can be spliced onto the next one.
One remaining case needs a host-side change: if the USB PHY stops inside a word, one TLP can complete with idle data words in place of the lost ones.
Related
- Build Gates for the checks that run before a bitstream is written.
- Supported Devices for the board list.
- The design records in the main repository, starting with MSIX_STATUS.md.