QDMA
Copyright (C) 2025 Advanced Micro Devices, Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
Userspace API for slash QDMA (Queue-based DMA) devices.
A QDMA device is a separate misc character device created for PF1, while the control device (ctldev) is created for PF2. Each PCI function gets at most one of each. Device nodes appear at /dev/slash_qdma_ctl0, /dev/slash_qdma_ctl1, etc.
Queue pair lifecycle:
slash_qdma_open() — open the QDMA device
slash_qdma_qpair_add() — create a queue pair (returns assigned qid)
slash_qdma_qpair_start() — activate for transfers
slash_qdma_qpair_get_fd() — obtain fd for data transfer
slash_qdma_qpair_stop() — deactivate
slash_qdma_qpair_del() — destroy
slash_qdma_close() — close the device
The fd from qpair_get_fd() supports read() for C2H (card-to-host) and write() for H2C (host-to-card) DMA transfers. Positional I/O via lseek()/pread()/pwrite() is also supported. splice(), mmap(), and poll() are not available.
Error conventions: int-returning functions return -1 with errno set. Pointer-returning functions return NULL with errno set.
Functions
-
struct slash_qdma *slash_qdma_open(const char *path)
Open a QDMA device.
- Parameters:
path – Path to the character device node. NULL returns NULL/EINVAL.
- Returns:
Heap-allocated handle on success, NULL on failure.
-
int slash_qdma_close(struct slash_qdma *qdma)
Close a QDMA device and free the handle.
- Parameters:
qdma – Handle from slash_qdma_open(), or NULL (returns -1/EINVAL).
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_info_read(struct slash_qdma *qdma, struct slash_qdma_info *info)
Read QDMA device capabilities.
- Parameters:
qdma – Open QDMA handle.
info – Caller-allocated struct, filled in on success.
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_qpair_add(struct slash_qdma *qdma, struct slash_qdma_qpair_add *req)
Create a new queue pair.
- Parameters:
qdma – Open QDMA handle.
req – In/out — caller sets configuration fields, kernel fills in the assigned queue id (and possibly other output fields).
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_qpair_start(struct slash_qdma *qdma, uint32_t qid)
Activate a queue pair for transfers.
- Parameters:
qdma – Open QDMA handle.
qid – Queue pair id from slash_qdma_qpair_add().
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_qpair_stop(struct slash_qdma *qdma, uint32_t qid)
Deactivate a queue pair.
- Parameters:
qdma – Open QDMA handle.
qid – Queue pair id.
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_qpair_del(struct slash_qdma *qdma, uint32_t qid)
Destroy a queue pair.
The kernel implicitly stops the queue if it is still running, so a separate stop call is not required before del.
- Parameters:
qdma – Open QDMA handle.
qid – Queue pair id.
- Returns:
0 on success, -1 on failure.
-
int slash_qdma_qpair_get_fd(struct slash_qdma *qdma, uint32_t qid, int flags)
Obtain a file descriptor for data transfer.
The returned fd supports read() (C2H) and write() (H2C). Positional I/O via lseek()/pread()/pwrite() is also available.
- Parameters:
qdma – Open QDMA handle.
qid – Queue pair id (must be started).
flags – Only O_CLOEXEC is accepted; the kernel returns -EINVAL for any other bits.
- Returns:
Non-negative fd on success, -1 on failure.
-
struct slash_qdma
- #include <qdma.h>
Handle to an open QDMA device.
@priv is NULL for real hardware handles. When slash_qdma_open() is called with “\@mock”, it points to an internal slash_qdma_mock context; callers should treat it as opaque.