Driver API: Types¶
Enumerations, handle types, and structures of the driver API. See Driver API for the concepts.
The HaDrv* types are declared in ha_driver_types.h, which ha_driver_api.h includes. A header that needs a driver
type but no driver function can include ha_driver_types.h alone. HaHostPtr, HaHostMemStats, HaDeviceMemStats,
HaLibrary_t and HaKernel_t are shared with the runtime API and are declared in ha_types.h.
Contents¶
| 이름 | 분류 | 설명 |
|---|---|---|
HaDrvDev |
Type alias | 디바이스 핸들 (참조 카운트) |
HaDrvDevAttr |
Enum | ha_drv_get_attr로 읽는 디바이스 속성 |
HaDrvObjKind |
Enum | ha_drv_obj_create / ha_drv_obj_destroy의 객체 종류 |
HaDrvEvent |
Type alias | 드라이버 이벤트 핸들 |
HaDrvStreamOpKind |
Enum | ha_drv_stream_post로 큐에 넣는 작업 종류 |
HaDrvStreamOp |
Struct | 스트림 작업 하나 (종류 + 페이로드) |
HaDrvStreamOpMemcpy |
Struct | HA_STREAM_OP_MEMCPY 페이로드 |
HaDrvStreamOpFree |
Struct | HA_STREAM_OP_FREE 페이로드 |
HaDrvStreamOpLoadFile |
Struct | HA_STREAM_OP_LOAD_FILE 페이로드 |
HaDrvStreamOpSampling |
Struct | HA_STREAM_OP_SET_SAMPLING 페이로드 |
HaDrvStreamOpEvent |
Struct | 이벤트 기록·대기 페이로드 |
HaDrvWaitKind |
Enum | ha_drv_wait의 대기 대상과 블로킹 여부 |
HaDrvKernel |
Type alias | 디바이스에 로드된 커널 핸들 |
HaLibrary_t / HaKernel_t |
Type alias | 커널 라이브러리 핸들과 라이브러리 안 커널 핸들 (디바이스 무관) |
HaHostPtr |
Type alias | 호스트 메모리 주소 (정수 표현) |
HaDrvHostMemTag |
Enum | 호스트 할당의 용도 |
HaDrvHostMemFlags |
Enum | 호스트 할당 플래그 |
HaDrvHostMemScope |
Type alias | 호스트 할당의 소유 범위 (예약) |
HaDrvHostMemAllocDesc |
Struct | ha_drv_host_mem_alloc 요청 |
HaHostMemStats |
Struct | 프로세스 호스트 메모리 통계 |
HaDeviceMemStats |
Struct | 디바이스 메모리 통계 |
HaDrvDev¶
Opaque device handle: one reference on an already-bootstrapped device, taken by
ha_drv_open and released by ha_drv_close.
시그니처
1 | |
HaDrvDevAttr¶
Attribute read by ha_drv_get_attr: a fact about the device (hardware, chip spec, PCI
placement), never how the driver runs it. New values are only appended.
| Value | Description |
|---|---|
HA_DEV_ATTR_VERSION |
Chip version, a HaDeviceVersion value. |
HA_DEV_ATTR_CORES_PER_GROUP |
NPU cores per core group. |
HA_DEV_ATTR_MAX_REUSE_NUM |
Maximum weight reuse count per core (chip spec). |
HA_DEV_ATTR_DRAM_WORD_SIZE |
DRAM word size in bytes. |
HA_DEV_ATTR_DRAM_CHANNELS |
Number of DRAM channels. |
HA_DEV_ATTR_DRAM_CHANNEL_STRIDE |
Byte distance between consecutive DRAM channels' address ranges. |
HA_DEV_ATTR_P2P_SUPPORTED |
1 if a copy may target another device's address (ha_drv_memcpy), else 0. |
HA_DEV_ATTR_PCI_DOMAIN |
PCI domain (segment). HaNotSupported if no physical device is bound. |
HA_DEV_ATTR_PCI_BUS |
PCI bus number. HaNotSupported if no physical device is bound. |
HA_DEV_ATTR_PCI_SLOT |
PCI device number. HaNotSupported if no physical device is bound. |
HA_DEV_ATTR_PCI_FUNC |
PCI function number. HaNotSupported if no physical device is bound. |
HA_DEV_ATTR_PEER_PRESENT_MASK |
Peers the kernel driver has registered; bit i = ha_drv_open index i, own bit always 0. HaNotSupported if no physical device is bound. |
HA_DEV_ATTR_PEER_MAPPED_MASK |
Peers whose User BAR is mapped into this device; bit i = ha_drv_open index i. Necessary but not sufficient for P2P (the PCIe fabric may still route upstream). HaNotSupported if no physical device is bound. |
HaDrvObjKind¶
Object kind for ha_drv_obj_create / ha_drv_obj_destroy.
| Value | Description |
|---|---|
HA_OBJ_STREAM |
Stream (HaStream_t). |
HA_OBJ_EVENT |
Driver event (HaDrvEvent). |
HaDrvEvent¶
Driver event, owned by the device it was created on (ha_drv_obj_create(HA_OBJ_EVENT)). Recorded and waited on
through ha_drv_stream_post (HA_STREAM_OP_RECORD_EVENT / HA_STREAM_OP_WAIT_EVENT) and
ha_drv_wait (HA_WAIT_EVENT_*). Distinct from the runtime's HaEvent_t.
시그니처
1 | |
HaDrvStreamOpKind¶
Op kind for ha_drv_stream_post. Kernel launches have their own function,
ha_drv_kernel_launch.
| Value | Description |
|---|---|
HA_STREAM_OP_MEMCPY |
Copy in memcpy.direction (H2D, D2H, or D2D on this device). |
HA_STREAM_OP_FREE |
Return free.ptr to its pool once a sync covers this op. |
HA_STREAM_OP_LOAD_FILE |
DMA load_file.len bytes of a file into device memory. |
HA_STREAM_OP_MARKER |
No side effect; only takes a seq (e.g. to sync up to this point). |
HA_STREAM_OP_SET_SAMPLING |
Apply sampling in order with the stream's launches. |
HA_STREAM_OP_RECORD_EVENT |
Record event.event at this point of the stream (once per event). |
HA_STREAM_OP_WAIT_EVENT |
Hold the stream's later ops until event.event completes. |
HaDrvStreamOp¶
One op for ha_drv_stream_post; kind selects the union member that is read.
| Member | Type | Description |
|---|---|---|
kind |
HaDrvStreamOpKind |
Selects the payload below. |
memcpy |
HaDrvStreamOpMemcpy |
HA_STREAM_OP_MEMCPY. |
free |
HaDrvStreamOpFree |
HA_STREAM_OP_FREE. |
load_file |
HaDrvStreamOpLoadFile |
HA_STREAM_OP_LOAD_FILE. |
sampling |
HaDrvStreamOpSampling |
HA_STREAM_OP_SET_SAMPLING. |
event |
HaDrvStreamOpEvent |
HA_STREAM_OP_RECORD_EVENT / HA_STREAM_OP_WAIT_EVENT. |
HA_STREAM_OP_MARKER reads no payload.
시그니처
1 2 3 4 5 6 7 8 9 10 | |
HaDrvStreamOpMemcpy¶
HA_STREAM_OP_MEMCPY payload. dst / src are host or device addresses per direction.
| Field | Type | Description |
|---|---|---|
dst |
HaDevicePtr |
Destination address. |
src |
HaDevicePtr |
Source address. |
len |
size_t |
Byte count. |
direction |
HaMemCpyDirection |
HostToDevice, DeviceToHost or DeviceToDevice. |
HaDrvStreamOpFree¶
HA_STREAM_OP_FREE payload. The stream orders the free (it takes effect once a sync covers it) and the
allocation's device takes it back, like CUDA cudaFreeAsync: owner may differ from the device the op is posted to; work on that stream may still use ptr until the free takes effect. If owner is reset before then, the free is dropped (its pool has already been released).
| Field | Type | Description |
|---|---|---|
ptr |
HaDevicePtr |
Allocation from ha_drv_malloc on owner. |
owner |
HaDrvDev |
Device ptr was allocated on; null for the device posted to. |
HaDrvStreamOpLoadFile¶
HA_STREAM_OP_LOAD_FILE payload.
| Field | Type | Description |
|---|---|---|
fd |
int |
Source file descriptor; must stay open until the op completes. |
off |
size_t |
Byte offset within the file. |
dst |
HaDevicePtr |
Device destination address. |
len |
size_t |
Byte count. |
HaDrvStreamOpSampling¶
HA_STREAM_OP_SET_SAMPLING payload; same fields as HaSetSamplingParams.
| Field | Type | Description |
|---|---|---|
core_id |
int |
Target NPU core ID. |
entry_index |
int |
Sampling table start index. |
entry_num |
int |
Number of entries to apply. |
top_p |
float |
Nucleus sampling probability threshold. |
top_k |
int |
Top-k sampling candidate count. |
temperature |
float |
Softmax temperature. |
repetition_penalty |
float |
Repetition suppression coefficient. |
pseudo_random |
float |
Pseudo-random seed forwarded to the sampling module's PRNG. |
HaDrvStreamOpEvent¶
HA_STREAM_OP_RECORD_EVENT / HA_STREAM_OP_WAIT_EVENT payload.
| Field | Type | Description |
|---|---|---|
event |
HaDrvEvent |
Event from ha_drv_obj_create(HA_OBJ_EVENT) on the same device. |
HaDrvWaitKind¶
What ha_drv_wait waits on (a stream, an event or the whole device) and whether it blocks.
| Value | Description |
|---|---|
HA_WAIT_STREAM_QUERY |
Non-blocking: has the stream finished everything posted to it? |
HA_WAIT_STREAM_SYNC |
Block until the stream finishes everything posted before this call. |
HA_WAIT_EVENT_QUERY |
Non-blocking: has the event's record completed? |
HA_WAIT_EVENT_SYNC |
Block until the event's record completes. |
HA_WAIT_DEVICE_SYNC |
Block until every stream of the device finishes what was posted before this call. |
HaDrvKernel¶
Loaded kernel, owned by the device that loaded it
(ha_drv_kernel_load_from_file or
ha_drv_kernel_load_from_library). Each load returns a new handle; loads of the same kernel share its device memory. A handle is never reused: a released handle, or one
from before a device reset, names no later kernel.
시그니처
1 | |
HaLibrary_t / HaKernel_t¶
Handles of a kernel library and of a kernel in it, issued by
ha_drv_library_load_data and
ha_drv_library_get_kernel. They belong to no device and stay valid until
the process ends; a HaKernel_t is not bound to any device until
ha_drv_kernel_load_from_library loads it as a HaDrvKernel. The
same handle types are used by the runtime API (Types). Declared in ha_types.h.
시그니처
1 2 | |
HaHostPtr¶
Host address of an allocation from ha_drv_host_mem_alloc, as an integer (the
HaDevicePtr convention). reinterpret_cast<void *>(ptr) gives the pointer; the same value is passed back to free it.
Declared in ha_types.h.
시그니처
1 | |
HaDrvHostMemTag¶
What a host allocation is for. Values are only appended, never changed, because they are part of the ABI.
Applications use HA_HOST_MEM_TAG_OTHER; the other values are used by runtime components or reserved.
| Value | Description |
|---|---|
HA_HOST_MEM_TAG_OTHER (0) |
Unclassified. |
HA_HOST_MEM_TAG_STAGING (1) |
ha_drv_memcpy_nd host staging (set by the runtime). |
HA_HOST_MEM_TAG_WC_INPUT (2) |
Internal runtime component use. |
HA_HOST_MEM_TAG_WC_SCRATCH (3) |
Internal runtime component use. |
HA_HOST_MEM_TAG_WC_OUTPUT (4) |
Internal runtime component use. |
HA_HOST_MEM_TAG_CCL_FIFO (5) |
Reserved; rejected by ha_drv_host_mem_alloc. |
HA_HOST_MEM_TAG_CCL_CONTROL (6) |
Reserved; rejected by ha_drv_host_mem_alloc. |
HaDrvHostMemFlags¶
Bits of HaDrvHostMemAllocDesc::flags. Bit 2 is reserved for shareable host memory.
| Value | Description |
|---|---|
HA_HOST_MEM_FLAG_NONE |
No flag. |
HA_HOST_MEM_FLAG_NO_POOL |
Bypass the pool: own allocation, returned to the OS when freed. |
HA_HOST_MEM_FLAG_ZERO |
Zero-fill on allocation; otherwise the contents are undefined. |
HaDrvHostMemScope¶
Owner scope of host allocations, the scope field of HaDrvHostMemAllocDesc. Reserved:
only NULL (the process scope) is accepted today.
시그니처
1 | |
HaDrvHostMemAllocDesc¶
Request for ha_drv_host_mem_alloc. Extensible: set struct_size to sizeof
as compiled. A struct_size smaller than the library's struct, or above 4096 bytes, is rejected; a larger one, from a
newer header, is accepted only if the bytes past what the library knows are zero.
| Member | Type | Description |
|---|---|---|
struct_size |
uint32_t |
sizeof(HaDrvHostMemAllocDesc) as the caller compiled it. |
flags |
uint32_t |
HaDrvHostMemFlags bits. |
tag |
HaDrvHostMemTag |
Purpose of the allocation; a reserved tag is rejected. |
reserved0 |
uint32_t |
Must be 0. |
size |
size_t |
Bytes, non-zero. The address is 64-byte aligned. |
scope |
HaDrvHostMemScope |
Must be NULL (owner scope; only the process scope is accepted today). |
HaHostMemStats¶
Host memory statistics of the whole process, every tag summed, read by
ha_drv_host_mem_get_stats. Extensible: set struct_size to sizeof before
the call; the library fills the whole fields that fit in that many bytes and stores the count it wrote. Each counter is read atomically, but
the set is not one snapshot. Both peaks restart from the current values with
ha_drv_host_mem_reset_peak_stats. Declared in ha_types.h.
| Member | Type | Description |
|---|---|---|
struct_size |
uint32_t |
In: sizeof(HaHostMemStats) as compiled. Out: bytes written. |
reserved0 |
uint32_t |
Written as 0. |
allocated_bytes |
uint64_t |
Bytes currently allocated (as requested, not rounded). |
peak_allocated_bytes |
uint64_t |
Highest allocated_bytes since the last peak reset. |
reserved_bytes |
uint64_t |
Held from the OS: cached freed memory included. |
peak_reserved_bytes |
uint64_t |
Highest reserved_bytes since the last peak reset. |
alloc_count |
uint64_t |
Allocations ever made. |
free_count |
uint64_t |
Allocations ever freed. |
HaDeviceMemStats¶
Device memory statistics of one device, read by ha_drv_device_mem_get_stats:
the runtime's pool counters and the driver's free DRAM figure. Extensible like HaHostMemStats: set struct_size to
sizeof before the call; the library fills the whole fields that fit and stores the count it wrote. Every peak restarts
from its current value with ha_drv_device_mem_reset_peak_stats.
Declared in ha_types.h; the fields are listed in the runtime API Types.