Driver API: Device Handle¶
Device bootstrap, handles, attributes, and reset. See Driver API for the concepts.
Contents¶
| 이름 | 분류 | 설명 |
|---|---|---|
ha_drv_scan_devices |
API | 현재 존재하는 디바이스를 비트맵으로 탐색 |
ha_drv_init |
API | 모든 디바이스를 스캔하고 부트스트랩 |
ha_drv_get_device_count |
API | 부트스트랩된 디바이스 수 조회 |
ha_drv_open |
API | 디바이스 핸들 열기 |
ha_drv_get_attr |
API | 디바이스 속성 하나 읽기 |
ha_drv_get_device_id |
API | 핸들이 가리키는 디바이스 인덱스 조회 |
ha_drv_is_ready |
API | 디바이스가 작업을 받을 수 있는 상태인지 확인 |
ha_drv_reset |
API | 디바이스 리셋 |
ha_drv_close |
API | 디바이스 핸들 닫기 |
ha_drv_deinit |
API | ha_drv_init을 되돌려 모든 디바이스 해제 |
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:
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; afterHaDeviceNotAvailable, call it again once a device is available.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 ownha_drv_close.- Use
devwith the memory, stream, event and kernel functions. ha_drv_close(dev)drops that handle's reference. Do not usedevafterwards.ha_drv_deinit()releases every device and everything it holds, once every handle is closed. A laterha_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_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.
시그니처 · 예제
1 | |
예제
1 2 3 4 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 4 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 4 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 4 | |
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.
시그니처 · 예제
1 | |
예제
1 2 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 | |
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).
시그니처 · 예제
1 | |
예제
1 2 3 4 5 | |
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.
시그니처 · 예제
1 | |
예제
1 2 | |
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.
시그니처 · 예제
1 | |
예제
1 2 3 4 | |