콘텐츠로 이동

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
typedef struct ha_dev_s *HaDrvDev;

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
typedef struct ha_drv_event *HaDrvEvent;

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
typedef struct {
  HaDrvStreamOpKind kind;
  union {
    HaDrvStreamOpMemcpy memcpy;
    HaDrvStreamOpFree free;
    HaDrvStreamOpLoadFile load_file;
    HaDrvStreamOpSampling sampling;
    HaDrvStreamOpEvent event;
  };
} HaDrvStreamOp;

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
typedef struct ha_kernel *HaDrvKernel;

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
typedef HaLibrary *HaLibrary_t;
typedef HaKernel *HaKernel_t;

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
typedef uint64_t HaHostPtr;

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
typedef struct ha_host_mem_scope *HaDrvHostMemScope;

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.