vrtd::Device

class Device

Value-type handle describing a vrtd device.

A Device carries its device number, name, and PCI metadata and routes operations back through its originating Session.

Lifetime

A Device becomes invalid if its originating Session is closed or moved. Any subsequent member call will throw.

Thread safety

Methods are thread-safe and may be called concurrently; they synchronize on the originating Session.

Public Functions

uint32_t getNum() const noexcept

Zero-based device index as seen by vrtd.

const std::string &getName() const noexcept

Human-readable device name.

Stable for the lifetime of the Device object.

const std::string &getBdf() const noexcept

PCI BDF string for this device.

uint16_t getVendorId() const noexcept

PCI vendor ID.

uint16_t getDeviceId() const noexcept

PCI device ID.

uint16_t getSubsystemVendorId() const noexcept

PCI subsystem vendor ID.

uint16_t getSubsystemDeviceId() const noexcept

PCI subsystem device ID.

Bar getBar(uint8_t num) const

Access a device BAR by index.

Notes

The returned Bar becomes invalid if the originating Session is later closed or moved.

Parameters:

num – BAR index.

Throws:

vrtd::Error – on error (e.g., invalid index or unusable session).

Returns:

Metadata handle for the requested BAR.

QdmaQpair createQdmaQpair(const struct slash_qdma_qpair_add &cfg) const

Create a QDMA qpair on this device.

Returns an owning QdmaQpair that will automatically delete the qpair on destruction.

Notes

The returned QdmaQpair becomes invalid if the originating Session is later closed or moved.

Parameters:

cfg – Qpair configuration parameters. The returned qpair exposes getQid().

Throws:

vrtd::Error – on error.

Returns:

An owning QdmaQpair.

Buffer openBuffer(BufferAllocType allocType, uint64_t size, uint64_t allocArg = 0, BufferAllocDir allocDir = BufferAllocDir::Bidirectional) const

Open a buffer (allocation + QDMA qpair) on this device.

Returns an owning Buffer that closes the returned FD on destruction.

Parameters:

  • allocType – Allocation type for the buffer.

  • size – Requested size in bytes.

  • allocArg – Allocation argument (HBM region index for HBM).

  • allocDir – QDMA transfer direction.

Throws:

vrtd::Error – on error.

Returns:

An owning Buffer.

inline Buffer openDdrBuffer(uint64_t size, BufferAllocDir allocDir = BufferAllocDir::Bidirectional) const

Convenience helper for DDR allocations.

inline Buffer openHbmBuffer(uint32_t region, uint64_t size, BufferAllocDir allocDir = BufferAllocDir::Bidirectional) const

Convenience helper for HBM allocations (fixed region).

inline Buffer openHbmVnocBuffer(uint64_t size, BufferAllocDir allocDir = BufferAllocDir::Bidirectional) const

Convenience helper for HBM VNOC allocations.

Buffer openRawBuffer(uint64_t phys_addr, uint64_t size, BufferAllocDir allocDir = BufferAllocDir::Bidirectional) const

Open a raw buffer (QDMA qpair at caller-specified device address, bypasses allocator).

Requires the raw-mem-access permission on this device. The caller is responsible for ensuring the address is valid and not in use.

Parameters:

  • phys_addr – Device physical address.

  • size – Size in bytes.

  • allocDir – QDMA transfer direction.

Throws:

vrtd::Error – on error.

Returns:

An owning Buffer.

void hotplugOp(HotplugOp op, uint8_t function = 0) const

Perform a PCIe hotplug operation for this device.

For board-level operations (Rescan, ResetSequence), function is ignored. For PF-level operations (Remove, ToggleSbr, Hotplug), function selects the PCI physical function (0-7).

Parameters:

  • op – One of HotplugOp.

  • function – PCI function number (0-7) for PF-level ops.

Throws:

vrtd::Error – on error.

inline void hotplugRescan() const

Convenience helper for bus rescan.

inline void hotplugRemove(uint8_t function) const

Convenience helper for remove.

Parameters:

function – PCI function number (0-7). Required.

inline void hotplugToggleSbr(uint8_t function) const

Convenience helper for SBR toggle.

Parameters:

function – PCI function number (0-7). Required.

inline void hotplug(uint8_t function) const

Convenience helper for a remove+rescan hotplug cycle.

Parameters:

function – PCI function number (0-7). Required.

void designWrite(int input_fd) const

Perform a design writer transfer using an input file descriptor.

The daemon takes ownership of the FD and blocks until the transfer completes.

Throws:

vrtd::Error – on error.

void designWriteFile(std::string_view path) const

Perform a design writer transfer from a file path.

Convenience helper that opens the path and passes the FD to the daemon.

Throws:

vrtd::Error – on error.

uint32_t getClockRate(ClockRegion region) const

Get the clock rate for a region.

Parameters:

region – Clock region.

Throws:

vrtd::Error – on error.

Returns:

Current rate in Hz.

uint32_t setClockRate(ClockRegion region, uint32_t rate_hz) const

Set the clock rate for a region.

Parameters:

  • region – Clock region.

  • rate_hz – Requested rate in Hz.

Throws:

vrtd::Error – on error.

Returns:

Achieved rate in Hz.

inline uint32_t getServiceClockRate() const

Convenience helper for service region get.

See also

getClockRate

inline uint32_t setServiceClockRate(uint32_t rate_hz) const

Convenience helper for service region set.

See also

setClockRate

inline uint32_t getUserClockRate() const

Convenience helper for user region get.

See also

getClockRate

inline uint32_t setUserClockRate(uint32_t rate_hz) const

Convenience helper for user region set.

See also

setClockRate

std::vector<SensorEntry> getSensorInfo() const

Query all sensor readings for this device.

Returns current values and statuses for all sensors (temperature, power, voltage, current) discovered via the AMI interface.

Throws:

vrtd::Error – on error.

Returns:

Vector of sensor entries.