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.

ShellType getShellType() const noexcept

Shell state reported by vrtd when this Device handle was created.

bool isJtag() const noexcept

Whether vrtd reported this device as JTAG-booted.

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, MmChannel mmChannel = MmChannel::Auto) 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.

  • mmChannel – AXI-MM/NoC channel selection (defaults to auto).

Throws:

vrtd::Error – on error.

Returns:

An owning Buffer.

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

Convenience helper for DDR allocations.

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

Convenience helper for HBM allocations (fixed region).

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

Convenience helper for HBM VNOC allocations.

Buffer openRawBuffer(uint64_t phys_addr, uint64_t size, BufferAllocDir allocDir = BufferAllocDir::Bidirectional, MmChannel mmChannel = MmChannel::Auto) 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.

  • mmChannel – AXI-MM/NoC channel selection (defaults to auto).

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 ResetSequence, function is ignored. For Remove and Hotplug, function selects the PCI physical function (0-7) or HotplugFunctionAll for all V80 PFs. ToggleSbr requires a single PCI physical function (0-7). Use Session::hotplugRescan() for bus rescan.

Parameters:

  • op – One of HotplugOp.

  • function – PCI function number (0-7), or HotplugFunctionAll where allowed.

Throws:

vrtd::Error – on error.

inline void hotplugRemove(uint8_t function = HotplugFunctionAll) const

Convenience helper for remove.

Parameters:

function – PCI function number (0-7), or HotplugFunctionAll for all PFs.

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 = HotplugFunctionAll) const

Convenience helper for a remove+rescan hotplug cycle.

Parameters:

function – PCI function number (0-7), or HotplugFunctionAll for all PFs.

void resetSequence(ShellType shellType = ShellType::Service) const

Reset the board and boot the requested shell.

Parameters:

shellType – Hardware shell to boot.

void setShellState(ShellType shellType, bool jtag) const

Set vrtd’s in-memory shell/JTAG state for this device.

Parameters:

  • shellType – Hardware shell believed to be booted.

  • jtag – Whether the device was booted from a JTAG-loaded image.

void designWrite(int input_fd, ShellType requiredShell = ShellType::Service) 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, ShellType requiredShell = ShellType::Service) 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.

void cfgmemProgram(int input_fd, uint8_t bootDevice, uint32_t partition) const

Program a PDI into cfgmem and reset into the programmed partition.

The daemon reads input_fd, programs partition on bootDevice through AMI, selects that partition for boot, and performs the vrtd-managed reset sequence.

Throws:

vrtd::Error – on error.

void cfgmemProgramFile(std::string_view path, uint8_t bootDevice, uint32_t partition) const

Program a PDI file into cfgmem.

Convenience helper that opens 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.