vrtd Client Functions

C client API for the V80 Runtime Daemon (vrtd).

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This library (libvrtd) provides a client interface to the VRT daemon (vrtd), which multiplexes access to SLASH-managed FPGA devices with permission control and multi‑tenancy.

Stack overview: slash (kernel module) <- libslash <- vrtd <- libvrtd <- libvrtdpp <- libvrt

Most functions return a vrtd_ret code. On success, functions return VRTD_RET_OK and populate their output parameters.

Defines

VRTD_STANDARD_PATH: Default UNIX domain socket path for the vrtd daemon.

Functions

int vrtd_connect(const char *path)

Connect to the vrtd UNIX domain socket.

Creates a SOCK_SEQPACKET connection to the vrtd daemon at path.

Parameters:

path – Absolute path to the vrtd socket (e.g. VRTD_STANDARD_PATH). Must not be NULL.

Returns:

On success, a non‑negative file descriptor to the socket. The caller owns this descriptor and must close it with close().

Returns:

On failure, returns -1 and sets errno.

enum vrtd_ret vrtd_raw_request(int fd, uint16_t opcode, const void *body, uint16_t body_size, void *resp_buf, size_t resp_bufsz, int *resp_fd, const int *req_fd)

Send a raw vrtd protocol request and receive the response.

This is a low‑level escape hatch for issuing arbitrary protocol opcodes. Most users should prefer higher‑level helpers (e.g., vrtd_get_* functions).

Note

On success, resp_buf contains exactly the response body bytes.

Note

resp_fd and req_fd are optional.

Warning

The request size must not exceed the protocol limit (e.g., VRTD_MSG_MAX_SIZE - sizeof(struct vrtd_req_header)).

Parameters:

fd – Connected vrtd socket file descriptor.
opcode – Protocol opcode to send (see vrtd_opcode in wire.h).
body – Pointer to request body buffer (may be NULL if body_size == 0).
body_size – Size of request body in bytes.
resp_buf – Buffer to receive the response body (may be NULL if no body expected).
resp_bufsz – Size of resp_buf in bytes.
resp_fd – Optional; if non‑NULL and the response carries a file descriptor (e.g., GET_BAR_FD), the received FD will be stored here. Otherwise ignored.
req_fd – Optional; if non‑NULL and *req_fd >= 0, the FD will be sent to the daemon via SCM_RIGHTS.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

enum vrtd_ret vrtd_get_num_devices(int fd, uint32_t *num_devices_out)

Query the number of available devices.

Parameters:

fd – Connected vrtd socket file descriptor.
num_devices_out – Output pointer to receive the device count.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

num_devices_out must not be NULL.

enum vrtd_ret vrtd_get_device_info(int fd, uint32_t dev, struct vrtd_device_info *info_out)

Get information about a device (name + PCI info).

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
info_out – Output device info (name + PCI metadata).

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

info_out must not be NULL.

enum vrtd_ret vrtd_get_device_by_bdf(int fd, const char *bdf, uint32_t *dev_out)

Look up a device index by PCI BDF.

Parameters:

fd – Connected vrtd socket file descriptor.
bdf – PCI BDF string (e.g., “0000:65:00.0”).
dev_out – Output device index.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

bdf and dev_out must not be NULL.

enum vrtd_ret vrtd_get_bar_info(int fd, uint32_t dev, uint8_t bar, struct slash_ioctl_bar_info *bar_info_out)

Retrieve information about a device BAR (Base Address Register).

Complementary to vrtd_get_bar_fd(); this returns metadata only.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
bar – BAR index.
bar_info_out – Output pointer for BAR info (layout, permissions, etc.).

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

bar_info_out must not be NULL.

enum vrtd_ret vrtd_get_bar_fd(int fd, uint32_t dev, uint8_t bar, int *fd_out, uint64_t *len_out)

Obtain a file descriptor for a device BAR, suitable for mmap().

Complementary to vrtd_get_bar_info(); this returns a handle to the BAR memory.

Note

The caller owns the returned FD and should close it when no longer needed (or use vrtd_open_bar_file()/vrtd_close_bar_file()).

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
bar – BAR index.
fd_out – Output pointer to receive the BAR file descriptor.
len_out – Output pointer to receive the BAR length in bytes.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

fd_out and len_out must not be NULL.

enum vrtd_ret vrtd_open_bar_file(int fd, uint32_t dev, uint8_t bar, struct slash_bar_file *bar_file_out)

Open a BAR and map it into the process address space.

Convenience helper that requests a BAR FD and performs mmap() into bar_file_out->map with length bar_file_out->len.

Warning

The caller must later call vrtd_close_bar_file() to unmap and close.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
bar – BAR index.
bar_file_out – Output structure receiving the BAR FD, length and mapping.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

bar_file_out must not be NULL.

Post:

On success, bar_file_out->fd is valid and bar_file_out->map is a writable shared mapping of size bar_file_out->len.

void vrtd_close_bar_file(struct slash_bar_file *bar_file_out)

Unmap and close resources acquired by vrtd_open_bar_file().

Safe to call with NULL and safe to call multiple times; on first successful call it unmaps, closes the FD, and clears bar_file_out->map.

Parameters:

bar_file_out – Pointer previously filled by vrtd_open_bar_file().

enum vrtd_ret vrtd_qdma_get_info(int fd, uint32_t dev, struct slash_qdma_info *info_out)

Query QDMA capabilities for a device.

Thin wrapper around the vrtd QDMA GET_INFO opcode. On success, fills info_out with the kernel’s view of the QDMA device.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
info_out – Output pointer for QDMA capability information.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

info_out must not be NULL.

enum vrtd_ret vrtd_qdma_qpair_add(int fd, uint32_t dev, struct slash_qdma_qpair_add *qpair_inout)

Create a QDMA qpair on a device.

On success, qpair_inout is updated with the kernel‑assigned qid.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
qpair_inout – In/out QDMA qpair parameters (see slash_qdma_qpair_add).

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

qpair_inout must not be NULL.

enum vrtd_ret vrtd_qdma_qpair_start(int fd, uint32_t dev, uint32_t qid)

Start, stop, or delete a QDMA qpair.

Convenience wrappers around the QDMA qpair OP opcode.

enum vrtd_ret vrtd_qdma_qpair_stop(int fd, uint32_t dev, uint32_t qid)

enum vrtd_ret vrtd_qdma_qpair_del(int fd, uint32_t dev, uint32_t qid)

enum vrtd_ret vrtd_qdma_qpair_get_fd(int fd, uint32_t dev, uint32_t qid, uint32_t flags, int *fd_out)

Obtain a read/write file descriptor for a QDMA qpair.

The descriptor can be used with read()/write() for C2H/H2C data transfer.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
qid – Qpair identifier as returned by vrtd_qdma_qpair_add().
flags – OR of O_CLOEXEC and 0 (other flags are rejected by the daemon).
fd_out – Output pointer to receive the qpair file descriptor.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

fd_out must not be NULL.

enum vrtd_ret vrtd_buffer_open(int fd, uint32_t dev, uint32_t alloc_type, uint32_t alloc_dir, uint64_t alloc_arg, uint64_t size_in, struct vrtd_buffer **buffer_out)

Open a buffer (allocation + QDMA qpair) and obtain its FD.

Requests a device memory allocation and creates a QDMA qpair for it. The returned file descriptor is owned by the caller and should be closed when no longer needed.

Note

The returned buffer must be released with vrtd_buffer_destroy().

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
alloc_type – Allocation type (one of enum vrtd_alloc_type).
alloc_dir – QDMA direction (one of enum vrtd_alloc_dir).
alloc_arg – Allocation argument (HBM region index for HBM).
size_in – Requested size in bytes.
buffer_out – Output pointer to receive the allocated buffer handle.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

buffer_out must not be NULL.

enum vrtd_ret vrtd_buffer_open_raw(int fd, uint32_t dev, uint64_t phys_addr, uint64_t size, uint32_t alloc_dir, struct vrtd_buffer **buffer_out)

Open a raw buffer (QDMA qpair at caller-specified device address) via vrtd.

Bypasses the allocator entirely — the caller is responsible for ensuring the address is valid and not in use. Requires the raw-mem-access permission.

Note

The returned buffer must be released with vrtd_buffer_destroy().

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
phys_addr – Caller-specified device physical address.
size – Size in bytes.
alloc_dir – One of vrtd_alloc_dir.
buffer_out – Output parameter set to the new buffer handle on success.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

buffer_out must not be NULL.

enum vrtd_ret vrtd_buffer_close(struct vrtd_buffer *buffer)

Close a buffer (release allocation + QDMA qpair) via vrtd.

On success or failure, the local buffer is destroyed and must not be used.

Parameters:

buffer – Buffer handle returned by vrtd_buffer_open().

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

buffer must not be NULL.

enum vrtd_ret vrtd_design_write(int fd, uint32_t dev, int input_fd)

Perform a design writer transfer for a device.

The input FD is sent to the daemon via SCM_RIGHTS. On success the daemon takes ownership of the FD and blocks until the transfer completes.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
input_fd – Input file descriptor to read from.

Returns:

VRTD_RET_OK on success; VRTD_RET_BUSY if a transfer is in progress; otherwise a vrtd_ret error code.

Pre:

input_fd must be a valid, readable file descriptor.

enum vrtd_ret vrtd_design_write_file(int fd, uint32_t dev, const char *path)

Open a file and perform a design writer transfer for a device.

Convenience helper that opens path read-only and passes the FD to the daemon via vrtd_design_write(). The FD is closed before returning.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
path – Path to the input file to transfer.

Returns:

VRTD_RET_OK on success; VRTD_RET_BUSY if a transfer is in progress; otherwise a vrtd_ret error code.

Pre:

path must not be NULL.

enum vrtd_ret vrtd_device_hotplug_op(int fd, uint32_t dev, uint8_t op, uint8_t function)

Perform a PCIe hotplug operation for a device.

For board-level operations (RESCAN, RESET_SEQUENCE), function is ignored. For PF-level operations (REMOVE, TOGGLE_SBR, HOTPLUG), function selects the PCI physical function (0-7).

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0-based).
op – One of vrtd_device_hotplug_op.
function – PCI function number (0-7) for PF-level ops.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

enum vrtd_ret vrtd_device_hotplug_rescan(int fd, uint32_t dev)

enum vrtd_ret vrtd_device_hotplug_remove(int fd, uint32_t dev, uint8_t function)

enum vrtd_ret vrtd_device_hotplug_toggle_sbr(int fd, uint32_t dev, uint8_t function)

enum vrtd_ret vrtd_device_hotplug_hotplug(int fd, uint32_t dev, uint8_t function)

enum vrtd_ret vrtd_clock_get_rate(int fd, uint32_t dev, uint32_t region, uint32_t *rate_hz_out)

Get the clock rate for a device region.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
region – One of vrtd_clock_region.
rate_hz_out – Output pointer for the current rate in Hz.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

rate_hz_out must not be NULL.

enum vrtd_ret vrtd_clock_set_rate(int fd, uint32_t dev, uint32_t region, uint32_t rate_hz_in, uint32_t *rate_hz_out)

Set the clock rate for a device region.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0‑based).
region – One of vrtd_clock_region.
rate_hz_in – Requested rate in Hz.
rate_hz_out – Output pointer for the achieved rate in Hz.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

rate_hz_out must not be NULL.

enum vrtd_ret vrtd_buffer_create_raw(int sock_fd, uint32_t dev, uint32_t alloc_type, uint32_t alloc_dir, uint64_t alloc_arg, uint64_t size, uint64_t phys_addr, int qpair_fd, struct vrtd_buffer **buffer_out)

enum vrtd_ret vrtd_buffer_destroy(struct vrtd_buffer *buffer)

Destroy a local buffer handle.

This does not notify the daemon. Use vrtd_buffer_close() to release the server-side allocation.

enum vrtd_ret vrtd_buffer_sync_to_device(struct vrtd_buffer *buffer, uint64_t offset, uint64_t size)

enum vrtd_ret vrtd_buffer_sync_from_device(struct vrtd_buffer *buffer, uint64_t offset, uint64_t size)

enum vrtd_ret vrtd_get_sensor_info(int fd, uint32_t dev, struct vrtd_sensor_entry *entries_out, uint32_t max_entries, uint32_t *num_entries_out)

Query sensor information for a device.

Retrieves all sensor readings (temperature, power, voltage, current) for the specified device. The daemon queries sensors on-demand via AMI.

The response is a variable-length message: a uint32_t sensor count followed by that many vrtd_sensor_entry structs. The caller provides a buffer large enough to hold the expected response.

Parameters:

fd – Connected vrtd socket file descriptor.
dev – Device index (0-based).
entries_out – Output buffer for sensor entries.
max_entries – Maximum number of entries entries_out can hold.
num_entries_out – Output pointer for the actual number of entries returned.

Returns:

VRTD_RET_OK on success; otherwise a vrtd_ret error code.

Pre:

entries_out and num_entries_out must not be NULL.

struct vrtd_buffer

#include <vrtd.h>

Public Members

int sock_fd

uint32_t dev

uint32_t alloc_type

uint32_t alloc_dir

uint64_t alloc_arg

uint64_t size

uint64_t phys_addr

int qpair_fd

void *buf