Skip to content

Driver API: Device Handle

Device bootstrap, handles, attributes, and reset. See Driver API for the concepts.

Contents

Name Kind Description
ha_drv_scan_devices API Probe the currently present devices as a bitmap
ha_drv_init API Scan and bootstrap every device
ha_drv_get_device_count API Get the number of bootstrapped devices
ha_drv_open API Open a device handle
ha_drv_get_attr API Read one device attribute
ha_drv_get_device_id API Get the device index a handle refers to
ha_drv_is_ready API Check whether the device can accept an op
ha_drv_reset API Reset the device
ha_drv_close API Close a device handle
ha_drv_deinit API Undo ha_drv_init and release every device

Device lifecycle

The lifecycle is two nested pairs. ha_drv_init / ha_drv_deinit bootstrap and release every device of the process; ha_drv_open / ha_drv_close take and drop one reference on a device that is already bootstrapped.

Scope Acquire Release Release fails when
Process (every device) ha_drv_init ha_drv_deinit A handle is still open: HaDeviceBusy, nothing is released
One handle ha_drv_open ha_drv_close — (the device itself stays bootstrapped)

A typical sequence:

  1. ha_drv_init() scans and bootstraps every device. While devices are bootstrapped it is a no-op, so it is safe to call more than once; after HaDeviceNotAvailable, call it again once a device is available.
  2. ha_drv_open(index, &dev) returns a handle on a bootstrapped device; it does not create a new device. Opening the same index again takes another reference on the same device and returns the same handle value, so the memory, streams and kernels are shared. Each successful open needs its own ha_drv_close.
  3. Use dev with the memory, stream, event and kernel functions.
  4. ha_drv_close(dev) drops that handle's reference. Do not use dev afterwards.
  5. ha_drv_deinit() releases every device and everything it holds, once every handle is closed. A later ha_drv_init() bootstraps them again.

ha_drv_reset works inside this lifecycle: it reinitializes one device and invalidates the streams, events, allocations and kernels created on it, while dev and every other open handle stay valid.

The remaining functions only read state and do not change the lifecycle:

Function Valid Reads
ha_drv_scan_devices Any time, including before ha_drv_init Which devices are present
ha_drv_get_device_count After ha_drv_init How many devices are bootstrapped
ha_drv_get_attr Open handle One device attribute
ha_drv_get_device_id Open handle The index the handle was opened for
ha_drv_is_ready Open handle Whether the device can take an op now
1
2
3
4
5
6
7
8
ha_drv_init();                              // process: bootstrap every device

HaDrvDev dev = nullptr;
ha_drv_open(0, &dev);                       // handle: one reference on device 0
// ... memory, streams, kernels on dev ...
ha_drv_close(dev);                          // handle released; device 0 stays bootstrapped

ha_drv_deinit();                            // process: release every device (all handles closed)

ha_drv_scan_devices

Probe the loaded plugin for currently present devices, without bootstrapping them.

Returns — Bitmap of present device indices (bit i set means device index i is present); 0 if none found.

Signature · Example
1
uint32_t ha_drv_scan_devices(void);

Example

1
2
3
4
uint32_t present = ha_drv_scan_devices();
for (int i = 0; i < 32; ++i) {
  if (present & (1u << i)) { /* device i is present in the system */ }
}

ha_drv_init

Scan and bootstrap every device the loaded plugin reports, so ha_drv_open can open them.

A no-op while devices are bootstrapped: it never re-creates a device an open handle points to. To bootstrap again, close every handle and call ha_drv_deinit first. Call it again after HaDeviceNotAvailable to retry once a device becomes available.

Returns — HaSuccess, or HaDeviceNotAvailable if no device was found or bootstrapped.

Signature · Example
1
HaError ha_drv_init(void);

Example

1
2
3
4
HaError err = ha_drv_init();
if (err == HaDeviceNotAvailable) {
  // Can be called again once a device is ready.
}

ha_drv_get_device_count

Get the number of currently bootstrapped devices (see ha_drv_init).

Parameter Direction Default Description
out out — Receives the device count.

Returns — HaSuccess; HaInvalidArgument if out is null; HaDeviceNotAvailable if zero.

Signature · Example
1
HaError ha_drv_get_device_count(int *out);

Example

1
2
3
4
int count = 0;
if (ha_drv_get_device_count(&count) == HaSuccess) {
  // count devices are bootstrapped
}

ha_drv_open

Open a handle on a device bootstrapped by ha_drv_init. Does not construct a new device. Takes a reference on the device; pair every successful open with one ha_drv_close, before calling ha_drv_deinit; the handle stays valid until it is closed.

Parameter Direction Default Description
index in — Device index.
out out — Receives the device handle on success.

Returns — HaSuccess; HaInvalidArgument if out is null; HaDeviceNotInitialized if no device with this index has been bootstrapped.

Signature · Example
1
HaError ha_drv_open(int index, HaDrvDev *out);

Example

1
2
3
4
HaDrvDev dev = nullptr;
if (ha_drv_open(0, &dev) == HaDeviceNotInitialized) {
  // ha_drv_init() must be called first.
}

ha_drv_get_attr

Read one device attribute (CUDA cuDeviceGetAttribute). See HaDrvDevAttr.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.
attr in — Attribute to read. One of HA_DEV_ATTR_VERSION, HA_DEV_ATTR_CORES_PER_GROUP, HA_DEV_ATTR_MAX_REUSE_NUM, HA_DEV_ATTR_DRAM_WORD_SIZE, HA_DEV_ATTR_DRAM_CHANNELS, HA_DEV_ATTR_DRAM_CHANNEL_STRIDE, HA_DEV_ATTR_P2P_SUPPORTED, HA_DEV_ATTR_PCI_DOMAIN, HA_DEV_ATTR_PCI_BUS, HA_DEV_ATTR_PCI_SLOT, HA_DEV_ATTR_PCI_FUNC, HA_DEV_ATTR_PEER_PRESENT_MASK, HA_DEV_ATTR_PEER_MAPPED_MASK (see HaDrvDevAttr).
value out — Receives the attribute's value.

Returns — HaSuccess; HaInvalidArgument if dev/value is null or attr is unknown; HaNotSupported if this device cannot report attr; HaDeviceNotReady during a reset.

Signature · Example
1
HaError ha_drv_get_attr(HaDrvDev dev, HaDrvDevAttr attr, int64_t *value);

Example

1
2
int64_t channels = 0;
ha_drv_get_attr(dev, HA_DEV_ATTR_DRAM_CHANNELS, &channels);

ha_drv_get_device_id

Return the device index that dev was opened with (the index passed to ha_drv_open).

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.

Returns — The device index, or -1 if dev is null.

Signature · Example
1
int ha_drv_get_device_id(HaDrvDev dev);

Example

1
2
3
HaDrvDev dev = nullptr;
ha_drv_open(2, &dev);
int index = ha_drv_get_device_id(dev);  // 2

ha_drv_is_ready

Whether dev is ready for an op: not torn down, with a valid native handle, and with its device memory manager set up. Reads state only and does not wait for a reset. Whether a device is selected for use (HaSetDevice) is the runtime's state, not the driver's.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.

Returns — true if the device is ready; false if dev is null or any check fails.

Signature · Example
1
bool ha_drv_is_ready(HaDrvDev dev);

Example

1
2
3
if (!ha_drv_is_ready(dev)) {
  // the device cannot be used yet
}

ha_drv_reset

Reset dev: stop its ops, drain its queued commands, release its memory pool, abort and reinitialize the device, then free all of its streams, events and cached kernels.

Every handle created on dev before the call (streams, events, allocations, kernels) is invalid afterwards; dev itself stays valid. The reset waits for the calls blocked on dev (stream / event sync, synchronous copy, kernel upload wait), which the abort wakes, before freeing what they use. If they do not return within the reset's drain timeout, the reset still completes but leaves those objects allocated (a later reset or the teardown frees them), so a late return never touches freed memory; such a call reports HaDeviceNotReady.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.

Returns — HaSuccess; HaInvalidArgument if dev is null; HaDeviceResetFailed if the device reset itself failed (the teardown above still ran).

Signature · Example
1
HaError ha_drv_reset(HaDrvDev dev);

Example

1
2
3
4
5
HaDrvKernel k = nullptr;
if (ha_drv_reset(dev) == HaSuccess) {
  // Every stream, event, allocation and kernel handle from before the reset is invalid. Re-create what is needed.
  ha_drv_kernel_load_from_file(dev, "kernels/add.elf", &k);
}

ha_drv_close

Release the reference ha_drv_open took; dev must not be used afterwards. The device itself stays bootstrapped until ha_drv_deinit, which requires every handle closed.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.

Returns — HaSuccess, or HaInvalidArgument if dev is null.

Signature · Example
1
HaError ha_drv_close(HaDrvDev dev);

Example

1
2
ha_drv_close(dev);
dev = nullptr;                          // do not reuse a closed handle

ha_drv_deinit

Undo ha_drv_init: release every bootstrapped device (its streams, events, kernels, memory and plugin handle). Every handle from ha_drv_open must be closed first (pair open with close, init with deinit); otherwise nothing is released. A later ha_drv_init bootstraps the devices again.

Returns — HaSuccess, also when nothing is bootstrapped; HaDeviceBusy if a handle is still open.

Signature · Example
1
HaError ha_drv_deinit(void);

Example

1
2
3
4
ha_drv_close(dev);                      // after closing every open handle
if (ha_drv_deinit() == HaDeviceBusy) {
  // a handle is still open, so nothing is released
}