콘텐츠로 이동

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:

  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.

시그니처 · 예제
1
uint32_t ha_drv_scan_devices(void);

예제

1
2
3
4
uint32_t present = ha_drv_scan_devices();
for (int i = 0; i < 32; ++i) {
  if (present & (1u << i)) { /* 디바이스 i가 시스템에 있음 */ }
}

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
HaError ha_drv_init(void);

예제

1
2
3
4
HaError err = ha_drv_init();
if (err == HaDeviceNotAvailable) {
  // 디바이스가 준비된 뒤 다시 호출할 수 있습니다.
}

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
HaError ha_drv_get_device_count(int *out);

예제

1
2
3
4
int count = 0;
if (ha_drv_get_device_count(&count) == HaSuccess) {
  // count개의 디바이스가 부트스트랩됨
}

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
HaError ha_drv_open(int index, HaDrvDev *out);

예제

1
2
3
4
HaDrvDev dev = nullptr;
if (ha_drv_open(0, &dev) == HaDeviceNotInitialized) {
  // ha_drv_init()을 먼저 호출해야 합니다.
}

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
HaError ha_drv_get_attr(HaDrvDev dev, HaDrvDevAttr attr, int64_t *value);

예제

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.

시그니처 · 예제
1
int ha_drv_get_device_id(HaDrvDev dev);

예제

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.

시그니처 · 예제
1
bool ha_drv_is_ready(HaDrvDev dev);

예제

1
2
3
if (!ha_drv_is_ready(dev)) {
  // 디바이스를 아직 사용할 수 없음
}

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
HaError ha_drv_reset(HaDrvDev dev);

예제

1
2
3
4
5
HaDrvKernel k = nullptr;
if (ha_drv_reset(dev) == HaSuccess) {
  // 리셋 이전의 스트림·이벤트·할당·커널 핸들은 모두 무효입니다. 필요한 것을 다시 만듭니다.
  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.

시그니처 · 예제
1
HaError ha_drv_close(HaDrvDev dev);

예제

1
2
ha_drv_close(dev);
dev = nullptr;                          // 닫은 핸들은 다시 쓰지 않습니다

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
HaError ha_drv_deinit(void);

예제

1
2
3
4
ha_drv_close(dev);                      // 열린 핸들을 모두 닫은 뒤
if (ha_drv_deinit() == HaDeviceBusy) {
  // 아직 닫지 않은 핸들이 있어 아무것도 해제되지 않음
}