dau-driver

Host I/O for DAU devices: discovery, registers, DMA, and job execution over XDMA

dau-driver is the host side of a DAU device. It discovers DAU-compatible XDMA endpoints, reads the canonical register block, decodes the device's capability advertisement, moves data over H2C/C2H DMA, allocates device storage, and runs the register-contract jobs the shells expose. All device semantics (register offsets, stream framing, capability words, record layouts) come from dau-core; this package owns transport and execution only.

• Linux hosts use the Xilinx XDMA character devices under /dev.
• macOS hosts use a DriverKit-based XDMA system extension through IOKit user-client calls, for register access and full H2C/C2H DMA.

from pathlib import Path

from dau_driver import discover_devices
from dau_driver.testing import FakeTransport, fake_device

devices = discover_devices()                       # the XDMA devices under /dev, when a board is installed
device = devices[0] if devices else fake_device(Path("."), FakeTransport())
device.check_bar_health()                          # all-ones reads fail here, not later
print(device.name, device.backend)                 # xdma0 linux-xdma
print(device.capabilities.dma)                     # alignment / max-transfer constraints
print(device.read_register_block_snapshot())       # the whole identity block
print(device.read_status())                        # the status word and last error

The Python execution paths (discovery, registers, transfers, storage, the scan, pipeline and fleet runners) also run against the in-memory fake transport above, and that is how the test suite exercises them. The kernel driver, the DriverKit extension and the native extension are tested on hardware.

Documentation

The full documentation is at dau-dev.github.io/dau-driver.

• Tutorial: Talk to a device without any hardware · Run a scan over many batches. Both drive a device end to end against the fake transport, no board required.
• How-to guides: Find and check a device · Move data to and from it · Run scan jobs across batches and cards · Allocate device storage · Fence a PCIe operation with the deadman · Develop and contribute.
• Reference: Device and discovery, including transfers, storage and errors · Execution contracts for stream, scan, pipeline and fleet jobs · Stream codec.
• Explanation: Why the driver owns almost nothing and where the dau-core boundary sits · Why staging overlaps compute, and when the runner stops · Why storage is handed out as generation-checked handles.

The examples directory holds end-to-end host flows (record-batch round trip, stream aggregation, the OHLCV pipeline job) that run against real hardware.

Installation

Requires Python 3.12 or newer.

pip install dau-driver

Wheels are published for CPython 3.12 and 3.13 on Linux (x86_64 and aarch64) and macOS (arm64). Elsewhere pip builds the small native extension from source, which needs a C++ toolchain.

On a host with a board, load the Linux XDMA module from kernel/linux-xdma/ or the macOS DriverKit extension from kernel/macos-xdma/; each has its own build and load instructions. Without one, the package still imports and runs against its fake transport. Whoever can open the character devices (Linux) or the user client (macOS) can read and write the card's memory and registers, so the operating system's device permissions are the access control.

License

Apache-2.0, except kernel/linux-xdma/, which is Xilinx's XDMA reference driver under its own Dual BSD/GPL terms. See kernel/README.md.