Wire Protocol

On-wire protocol definitions shared between the vrtd daemon and its clients.

On‑wire protocol for vrtd (V80 Runtime Daemon).

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.

Transport:

UNIX domain sockets (AF_UNIX, SOCK_SEQPACKET). Messages are record‑oriented.
File descriptors may be sent out‑of‑band using SCM_RIGHTS.

Framing:

Each message = { header, body }.
Total size (header + body) MUST be <= VRTD_MSG_MAX_SIZE.

Sequencing:

Requests carry a client‑chosen vrtd_req_header::seqno that is echoed unmodified by the server in vrtd_resp_header::seqno.

Versioning/Extensibility:

Unknown opcodes result in VRTD_RET_BAD_REQUEST.
New fields may be added at the end of messages; older peers must ignore trailing bytes up to vrtd_resp_header::size.

Security:

Server enforces permissions; failures surface as VRTD_RET_AUTH_ERROR.

Defines

VRTD_MSG_MAX_SIZE: Maximum total size (header + body) for any vrtd message in bytes.

VRTD_PCI_BDF_LEN

VRTD_DEVICE_HOTPLUG_FUNCTION_ALL

VRTD_SENSOR_MAX_ENTRIES: Maximum number of sensor entries that fit in a single response message.

Enums

enum vrtd_opcode

Operations the client can request from the server.

Note

Unknown/unsupported opcodes yield VRTD_RET_BAD_REQUEST.

Values:

enumerator VRTD_REQ_GET_NUM_DEVICES: Query the number of SLASH devices.

enumerator VRTD_REQ_GET_DEVICE_INFO: Query basic information about a device.

enumerator VRTD_REQ_GET_BAR_INFO: Query metadata about a device BAR.

enumerator VRTD_REQ_GET_BAR_FD: Obtain a device BAR file descriptor via SCM_RIGHTS.

enumerator VRTD_REQ_QDMA_GET_INFO: Query QDMA capabilities of a device.

enumerator VRTD_REQ_QDMA_QPAIR_ADD: Create a QDMA qpair on a device.

enumerator VRTD_REQ_QDMA_QPAIR_OP: Apply an operation (start/stop/del) to a QDMA qpair.

enumerator VRTD_REQ_QDMA_QPAIR_GET_FD: Obtain a read/write file descriptor for a QDMA qpair.

enumerator VRTD_REQ_DESIGN_WRITE: Perform a design writer transfer by passing an input fd via SCM_RIGHTS.

enumerator VRTD_REQ_CLOCK_OP: Get or set a clock rate for the service/user region.

enumerator VRTD_REQ_BUFFER_OPEN: Open a buffer (allocation + QDMA qpair) and return a qpair fd.

enumerator VRTD_REQ_BUFFER_CLOSE: Close a buffer (release allocation + QDMA qpair).

enumerator VRTD_REQ_GET_DEVICE_BY_BDF: Query a device index by PCI BDF.

enumerator VRTD_REQ_DEVICE_HOTPLUG_OP: Perform a PCIe hotplug operation for a device.

enumerator VRTD_REQ_GET_SENSOR_INFO: Query sensor information for a device via AMI.

enumerator VRTD_REQ_BUFFER_OPEN_RAW: Open a raw buffer (QDMA qpair at caller-specified device address, bypassing allocator).

enumerator VRTD_REQ_CFGMEM_PROGRAM: Program a PDI into cfgmem via AMI and reset into the programmed partition.

enumerator VRTD_REQ_CFGMEM_PROGRAM_START: Start a cfgmem program job and return a job identifier immediately.

enumerator VRTD_REQ_CFGMEM_PROGRAM_STATUS: Query progress for a cfgmem program job.

enumerator VRTD_REQ_SET_SHELL_STATE: Set vrtd’s in-memory shell/JTAG state for a device.

enum vrtd_ret

Return codes for vrtd operations.

Warning

VRTD_RET_BAD_LIB_CALL and VRTD_RET_BAD_CONN are client‑local and are never returned by the server on the wire.

Values:

enumerator VRTD_RET_OK

enumerator VRTD_RET_BAD_LIB_CALL: Bad library call to libvrtd. This code will not be returned on the wire.

enumerator VRTD_RET_BAD_CONN: libvrtd could not connect to vrtd. This code will not be returned on the wire.

enumerator VRTD_RET_BAD_REQUEST: Malformed request.

enumerator VRTD_RET_INVALID_ARGUMENT: Invalid argument.

enumerator VRTD_RET_NOEXIST: Requested resource does not exist.

enumerator VRTD_RET_INTERNAL_ERROR: Internal error in the vrtd daemon. Check the vrtd log.

enumerator VRTD_RET_AUTH_ERROR: User does not have permission to execute request.

enumerator VRTD_RET_BUSY: Requested resource is busy.

enumerator VRTD_RET_SHELL_LOCKED: Device is JTAG-booted and will not be auto-reset for shell switching.

enum vrtd_alloc_type

Allocation types for buffer requests.

Values:

enumerator VRTD_ALLOC_TYPE_DDR

enumerator VRTD_ALLOC_TYPE_HBM

enumerator VRTD_ALLOC_TYPE_HBM_VNOC

enum vrtd_alloc_dir

Direction for data transfers for allocated buffer.

Values:

enumerator VRTD_ALLOC_DIR_BIDIRECTIONAL

enumerator VRTD_ALLOC_DIR_HOST_TO_DEVICE

enumerator VRTD_ALLOC_DIR_DEVICE_TO_HOST

enum vrtd_shell_type

Values:

enumerator VRTD_SHELL_UNKNOWN

enumerator VRTD_SHELL_SERVICE

enumerator VRTD_SHELL_COMPUTE

enum vrtd_cfgmem_program_state

Values:

enumerator VRTD_CFGMEM_PROGRAM_STATE_QUEUED

enumerator VRTD_CFGMEM_PROGRAM_STATE_RUNNING

enumerator VRTD_CFGMEM_PROGRAM_STATE_DONE

enumerator VRTD_CFGMEM_PROGRAM_STATE_FAILED

enum vrtd_cfgmem_program_phase

Values:

enumerator VRTD_CFGMEM_PROGRAM_PHASE_QUEUED

enumerator VRTD_CFGMEM_PROGRAM_PHASE_OPENING_AMI

enumerator VRTD_CFGMEM_PROGRAM_PHASE_DOWNLOADING_PDI

enumerator VRTD_CFGMEM_PROGRAM_PHASE_SELECTING_PARTITION

enumerator VRTD_CFGMEM_PROGRAM_PHASE_RESET_PREPARING

enumerator VRTD_CFGMEM_PROGRAM_PHASE_REMOVING_PCIE

enumerator VRTD_CFGMEM_PROGRAM_PHASE_TOGGLING_SBR

enumerator VRTD_CFGMEM_PROGRAM_PHASE_RESCANNING_PCIE

enumerator VRTD_CFGMEM_PROGRAM_PHASE_REDISCOVERING_DEVICE

enumerator VRTD_CFGMEM_PROGRAM_PHASE_DONE

enumerator VRTD_CFGMEM_PROGRAM_PHASE_FAILED

enum vrtd_device_hotplug_op

Values:

enumerator VRTD_DEVICE_HOTPLUG_OP_RESCAN

enumerator VRTD_DEVICE_HOTPLUG_OP_REMOVE

enumerator VRTD_DEVICE_HOTPLUG_OP_TOGGLE_SBR

enumerator VRTD_DEVICE_HOTPLUG_OP_HOTPLUG

enumerator VRTD_DEVICE_HOTPLUG_OP_RESET_SEQUENCE

enum vrtd_clock_region

Values:

enumerator VRTD_CLOCK_REGION_SERVICE

enumerator VRTD_CLOCK_REGION_USER

enum vrtd_clock_op

Values:

enumerator VRTD_CLOCK_OP_GET

enumerator VRTD_CLOCK_OP_SET

struct vrtd_pci_info

#include <wire.h>

Public Members

char bdf[32]

uint16_t vendor_id

uint16_t device_id

uint16_t subsystem_vendor_id

uint16_t subsystem_device_id

struct vrtd_req_header

#include <wire.h>

Public Members

uint16_t size: Size of the request body (not including the header).

uint16_t opcode: See vrtd_opcode.

uint32_t seqno: Sequence number (this will simply be echoed by the server in the response header).

struct vrtd_resp_header

#include <wire.h>

Public Members

uint16_t size: Size of the response body (not including the header).

uint16_t ret: See vrtd_ret.

uint32_t seqno: Sequence number (this is simply echoed from the request header).

struct vrtd_req_get_num_devices

#include <wire.h>

Placeholder body to avoid empty-struct ABI pitfalls across C/C++.

Note

Must be set to zero by clients; servers must ignore its value.

Public Members

uint8_t zero

struct vrtd_resp_get_num_devices

#include <wire.h>

Public Members

uint32_t num_devices: Number of SLASH devices known to the server. They are identified by numbers in the range [0, n).

struct vrtd_req_get_device_info

#include <wire.h>

Public Members

uint32_t dev_number: The device for which to get info. An index in the range [0, n).

struct vrtd_device_info

#include <wire.h>

Public Members

char name[128]: The name of the device.

struct vrtd_pci_info pci: PCIe metadata (BDF and IDs).

uint8_t shell_type: Current shell state known by vrtd (enum vrtd_shell_type).

uint8_t jtag: Non-zero if vrtd believes the device is JTAG-booted.

struct vrtd_resp_get_device_info

#include <wire.h>

Public Members

struct vrtd_device_info info

struct vrtd_req_get_device_by_bdf

#include <wire.h>

Public Members

char bdf[32]: PCI BDF string (e.g., 0000:65:00.0)

struct vrtd_resp_get_device_by_bdf

#include <wire.h>

Public Members

uint32_t dev_number: Device index (0-based).

struct vrtd_req_get_bar_info

#include <wire.h>

Public Members

uint32_t dev_number: The device for which to get info. An index in the range [0, n).

uint8_t bar_number: The BAR for which to get info. An index in the range [0, 6).

struct vrtd_resp_get_bar_info

#include <wire.h>

Public Members

struct slash_ioctl_bar_info bar_info: The structure with BAR information.

struct vrtd_req_get_bar_fd

#include <wire.h>

Public Members

uint32_t dev_number: The device for who’s BAR to get a file descriptor. An index in the range [0, n).

uint8_t bar_number: The BAR for which to get a file descriptor. An index in the range [0, 6).

struct vrtd_resp_get_bar_fd

#include <wire.h>

Response to VRTD_REQ_GET_BAR_FD.

The BAR file descriptor is sent out-of-band via SCM_RIGHTS in the same message and is present only when vrtd_resp_header::ret == VRTD_RET_OK.

Public Members

uint64_t len: Size of the BAR address space; suitable for mmap.

struct vrtd_req_qdma_get_info

#include <wire.h>

Request QDMA capability information for a device.

Complementary to slash_qdma_info; this wraps the libslash QDMA info query and exposes it over the vrtd protocol.

Public Members

uint32_t dev_number: The device for which to get QDMA info. An index in the range [0, n).

struct vrtd_resp_qdma_get_info

#include <wire.h>

Public Members

struct slash_qdma_info info: QDMA capabilities for the device.

struct vrtd_req_qdma_qpair_add

#include <wire.h>

Request creation of a QDMA qpair.

The slash_qdma_qpair_add payload is passed through to the kernel and the resulting qid is returned in the response.

Public Members

uint32_t dev_number: Device index (0-based).

struct slash_qdma_qpair_add add: Qpair creation parameters.

struct vrtd_resp_qdma_qpair_add

#include <wire.h>

Public Members

struct slash_qdma_qpair_add add: Echoed qpair parameters with qid filled in.

struct vrtd_req_qdma_qpair_op

#include <wire.h>

Request an operation on an existing QDMA qpair.

op uses the same numeric values as SLASH_QDMA_QUEUE_OP_START and friends.

Public Members

uint32_t dev_number: Device index (0-based).

uint32_t qid: Qpair identifier as returned by qpair_add.

uint32_t op: One of SLASH_QDMA_QUEUE_OP_{START,STOP,DEL}.

struct vrtd_resp_qdma_qpair_op

#include <wire.h>

Public Members

uint8_t zero: Placeholder to avoid empty-struct ABI issues.

struct vrtd_req_qdma_qpair_get_fd

#include <wire.h>

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

One or more qpair FDs are sent out-of-band via SCM_RIGHTS when vrtd_resp_header::ret == VRTD_RET_OK. The response body reports the number of descriptors attached.

Public Members

uint32_t dev_number: Device index (0-based).

uint32_t qid: Qpair identifier as returned by qpair_add.

uint32_t flags: Only O_CLOEXEC is currently honored.

struct vrtd_resp_qdma_qpair_get_fd

#include <wire.h>

Public Members

uint8_t zero: Placeholder; all data is carried via SCM_RIGHTS.

struct vrtd_req_buffer_open

#include <wire.h>

Request a buffer (allocation + QDMA qpair) and a qpair FD.

The qpair FD is sent out-of-band via SCM_RIGHTS when vrtd_resp_header::ret == VRTD_RET_OK.

Public Members

uint32_t dev_number: Device index (0-based).

uint32_t alloc_type: One of enum vrtd_alloc_type.

uint32_t alloc_dir: One of enum vrtd_alloc_dir.

uint32_t mm_channel: AXI-MM/NoC channel selection (enum vrtd_mm_channel).

uint64_t alloc_arg: Allocation argument (HBM region index for HBM).

uint64_t size: Requested size in bytes.

struct vrtd_resp_buffer_open

#include <wire.h>

Public Members

uint64_t size: Allocated size in bytes (rounded up to subregion).

uint64_t phys_addr: Device physical address of the allocation.

uint32_t qpair_count: Number of QDMA queue pairs (AXI-MM/NoC channels) owned by the single transfer FD sent via SCM_RIGHTS (1 or 2). When two qpairs are bound (an mm_channel == AUTO request), their qpair_index ordering is fixed: index 0 is pinned to channel 0 and index 1 to channel 1, so the client can apply the V80 placement policy deterministically. Exactly one FD is always sent regardless of this count.

struct vrtd_req_buffer_close

#include <wire.h>

Request closing a buffer (release allocation + QDMA qpair).

Public Members

uint32_t dev_number: Device index (0-based).

uint64_t phys_addr: Device physical address of the allocation.

uint64_t size: Allocated size in bytes.

struct vrtd_resp_buffer_close

#include <wire.h>

Public Members

uint8_t zero: Placeholder to avoid empty-struct ABI issues.

struct vrtd_req_buffer_open_raw

#include <wire.h>

Request a raw buffer (QDMA qpair at caller-specified device address).

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

A single transfer FD is sent out-of-band via SCM_RIGHTS when vrtd_resp_header::ret == VRTD_RET_OK. The response body reports how many queue pairs (channels) that FD owns.

Public Members

uint32_t dev_number: Device index (0-based).

uint32_t alloc_dir: One of enum vrtd_alloc_dir.

uint32_t mm_channel: AXI-MM/NoC channel selection (enum vrtd_mm_channel).

uint64_t phys_addr: Caller-specified device physical address (bypasses allocator).

uint64_t size: Size in bytes.

struct vrtd_resp_buffer_open_raw

#include <wire.h>

Public Members

uint32_t qpair_count: Number of QDMA queue pairs (channels) owned by the single transfer FD sent via SCM_RIGHTS (1 or 2). Same qpair_index-to-channel ordering as vrtd_resp_buffer_open.

struct vrtd_req_design_write

#include <wire.h>

Request a design writer transfer.

The input file descriptor is sent out-of-band via SCM_RIGHTS.

Public Members

uint32_t dev_number: Device index (0-based).

uint8_t required_shell: One of vrtd_shell_type.

struct vrtd_resp_design_write

#include <wire.h>

Public Members

uint8_t zero: Placeholder; all data is carried via SCM_RIGHTS.

struct vrtd_req_cfgmem_program

#include <wire.h>

Request cfgmem programming through AMI.

The PDI file descriptor is sent out-of-band via SCM_RIGHTS. On success, the daemon programs partition on boot_device, selects that partition for boot, and performs the vrtd-managed reset sequence.

Public Members

uint32_t dev_number: Device index (0-based).

uint8_t boot_device: AMI boot device selector (primary/secondary).

uint8_t reserved[3]: Reserved, must be zero.

uint32_t partition: Flash partition to program and boot.

struct vrtd_resp_cfgmem_program

#include <wire.h>

Public Members

uint8_t zero: Placeholder; all data is carried via SCM_RIGHTS.

struct vrtd_cfgmem_program_status

#include <wire.h>

Progress snapshot for a cfgmem programming job.

Public Members

uint64_t job_id: Job identifier returned by CFGMEM_PROGRAM_START.

uint32_t state: One of enum vrtd_cfgmem_program_state.

uint32_t phase: One of enum vrtd_cfgmem_program_phase.

uint64_t bytes_written: PDI bytes written so far, if known.

uint64_t bytes_total: Total PDI bytes to write, if known.

uint64_t elapsed_msec: Milliseconds since job submission.

uint16_t result: Final VRTD_RET_* when done/failed, otherwise VRTD_RET_OK.

struct vrtd_req_cfgmem_program_start

#include <wire.h>

Public Members

uint32_t dev_number: Device index (0-based).

uint8_t boot_device: AMI boot device selector (primary/secondary).

uint8_t reserved[3]: Reserved, must be zero.

uint32_t partition: Flash partition to program and boot.

struct vrtd_resp_cfgmem_program_start

#include <wire.h>

Public Members

uint64_t job_id: Job identifier to use with CFGMEM_PROGRAM_STATUS.

struct vrtd_req_cfgmem_program_status

#include <wire.h>

Public Members

uint64_t job_id: Job identifier returned by CFGMEM_PROGRAM_START.

struct vrtd_resp_cfgmem_program_status

#include <wire.h>

Public Members

struct vrtd_cfgmem_program_status status

struct vrtd_req_device_hotplug_op

#include <wire.h>

Request a PCIe hotplug operation for a device.

RESCAN is device-independent; dev_number and function are ignored. For RESET_SEQUENCE, shell_type selects the shell partition to boot and function is ignored.

For REMOVE and HOTPLUG, function selects the PCI physical function (0-7) or VRTD_DEVICE_HOTPLUG_FUNCTION_ALL for all V80 PFs. TOGGLE_SBR always requires a single PCI physical function (0-7).

Public Members

uint32_t dev_number: Device index (0-based).

uint8_t op: One of vrtd_device_hotplug_op.

uint8_t function: PCI function number (0-7), or FUNCTION_ALL where allowed.

uint8_t shell_type: One of vrtd_shell_type for RESET_SEQUENCE.

struct vrtd_resp_device_hotplug_op

#include <wire.h>

Public Members

uint8_t zero: Placeholder to avoid empty-struct ABI issues.

struct vrtd_req_set_shell_state

#include <wire.h>

Set vrtd’s in-memory shell state for a device.

Requires the same hotplug permission as disruptive PCIe operations. The daemon accepts shell_type only while the current shell is UNKNOWN; jtag is a set-only flag that is cleared by device rediscovery/reset.

Public Members

uint32_t dev_number: Device index (0-based).

uint8_t shell_type: One of vrtd_shell_type.

uint8_t jtag: Non-zero to mark the device as JTAG-booted.

struct vrtd_resp_set_shell_state

#include <wire.h>

Public Members

uint8_t zero: Placeholder to avoid empty-struct ABI issues.

struct vrtd_req_clock_op

#include <wire.h>

Request a clock operation (get/set) for a region.

Public Members

uint32_t dev_number: Device index (0-based).

uint32_t rate_hz: Desired rate for SET; ignored for GET.

uint8_t op: One of vrtd_clock_op.

uint8_t region: One of vrtd_clock_region.

struct vrtd_resp_clock_op

#include <wire.h>

Public Members

uint32_t rate_hz: Current/achieved rate for GET/SET.

struct vrtd_sensor_entry

#include <wire.h>

A single sensor reading.

Each entry corresponds to one (sensor-name, sensor-type) pair. For example, “vccint” may produce separate entries for temperature, voltage, current, and power.

Public Members

char name[64]: Sensor name (e.g., “vccint”).

uint8_t type: Sensor type bitmask (1=temp, 2=current, 4=voltage, 8=power).

uint8_t status: Sensor status (0x01 = OK, see AMI sensor status codes).

int8_t unit_mod: Unit modifier exponent (e.g., -3 for milli-).

uint8_t _pad: Reserved, must be zero.

int32_t value: Sensor reading (apply 10^unit_mod to get base unit value).

struct vrtd_req_get_sensor_info

#include <wire.h>

Request sensor information for a device.

The daemon opens an AMI handle, discovers sensors, reads their values, and returns them all in the response.

Public Members

uint32_t dev_number: Device index (0-based).

struct vrtd_resp_get_sensor_info

#include <wire.h>

Response to VRTD_REQ_GET_SENSOR_INFO.

Contains a variable number of sensor entries. The actual response size is sizeof(num_sensors) + num_sensors * sizeof(struct vrtd_sensor_entry).

Public Members

uint32_t num_sensors: Number of sensor entries following.

struct vrtd_sensor_entry sensors[]: Variable-length array of sensor entries.