```{toctree}
---
maxdepth: 2
hidden: true
---



docs/src/tutorial/first-device.md

docs/src/tutorial/first-scan-run.md

docs/src/how-to/find-a-device.md

docs/src/how-to/move-data.md

docs/src/how-to/run-scan-jobs.md

docs/src/how-to/allocate-device-storage.md

docs/src/how-to/arm-the-deadman.md

docs/src/how-to/develop.md

docs/src/reference/device-and-discovery.md

docs/src/reference/execution-contracts.md

docs/src/reference/stream-codec.md

docs/src/explanation/transport-boundary.md

docs/src/explanation/overlapped-staging.md

docs/src/explanation/storage-handles.md


```

# dau-driver

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

[![Build Status](https://github.com/dau-dev/dau-driver/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/dau-dev/dau-driver/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/dau-dev/dau-driver/branch/main/graph/badge.svg)](https://codecov.io/gh/dau-dev/dau-driver)
[![License](https://img.shields.io/github/license/dau-dev/dau-driver)](https://github.com/dau-dev/dau-driver)
[![PyPI](https://img.shields.io/pypi/v/dau-driver.svg)](https://pypi.python.org/pypi/dau-driver)

`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.

```python
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](https://dau-dev.github.io/dau-driver/).

- **Tutorial**: [Talk to a device without any hardware](docs/src/tutorial/first-device.md) ·
  [Run a scan over many batches](docs/src/tutorial/first-scan-run.md). Both drive a device end
  to end against the fake transport, no board required.
- **How-to guides**: [Find and check a device](docs/src/how-to/find-a-device.md) ·
  [Move data to and from it](docs/src/how-to/move-data.md) ·
  [Run scan jobs](docs/src/how-to/run-scan-jobs.md) across batches and cards ·
  [Allocate device storage](docs/src/how-to/allocate-device-storage.md) ·
  [Fence a PCIe operation with the deadman](docs/src/how-to/arm-the-deadman.md) ·
  [Develop and contribute](docs/src/how-to/develop.md).
- **Reference**: [Device and discovery](docs/src/reference/device-and-discovery.md), including
  transfers, storage and errors · [Execution contracts](docs/src/reference/execution-contracts.md)
  for stream, scan, pipeline and fleet jobs · [Stream codec](docs/src/reference/stream-codec.md).
- **Explanation**: [Why the driver owns almost nothing](docs/src/explanation/transport-boundary.md)
  and where the `dau-core` boundary sits ·
  [Why staging overlaps compute, and when the runner stops](docs/src/explanation/overlapped-staging.md) ·
  [Why storage is handed out as generation-checked handles](docs/src/explanation/storage-handles.md).

The [examples](https://github.com/dau-dev/dau-driver/tree/main/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.

```bash
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](kernel/README.md).