Driver API (ha_drv_*)¶
The driver API (ha_drv_*) is a device-handle-based API: every function that operates on a device takes a device handle. It
corresponds to the CUDA Driver API. For the
concepts and the detailed call sequence, see the Driver API guide.
1 | |
ha_driver_api.h includes ha_driver_types.h, which declares the driver types (HaDrv*). A header that needs a
driver type but no driver function can include ha_driver_types.h alone.
Build and link settings¶
Link the hart::ha_umd_core target of the CMake package hart. When you also use the higher-level runtime API,
linking hart::ha_hart alone is enough.
1 2 | |
Sections¶
| Page | Contents |
|---|---|
| Device | Device bootstrap, handle open/close, device attribute queries, device reset |
| Memory | Device memory allocation and release, 1-D/N-D data copy (memcpy), device memory statistics, host memory allocation |
| Execution | Kernel library registration and kernel lookup, kernel load (file / library), launch and release |
| Streams & Events | Stream and event creation and destruction, posting ops, host-side waits |
| TLB | Static KV-cache TLB and page-table TLB configuration |
| Types | Enumerations, handle types, and structure definitions |
Common rules¶
These rules apply to every driver API entry point and are not repeated on the individual pages.
- Calls take a device handle: every function that operates on a device takes a device handle as its first
argument. A handle is created with
ha_drv_open()and released withha_drv_close(). No function controls several devices at once. The following functions take no device handle:ha_drv_scan_devices,ha_drv_init,ha_drv_deinit,ha_drv_get_device_countandha_drv_open, used before a handle exists; the host memory functions (ha_drv_host_mem_*) and kernel library functions (ha_drv_library_*), which do not depend on a device; andha_drv_launch_args_set_*, which only change an existing argument list. - Default stream (
HA_STREAM_DEFAULT): the default stream the calling thread uses on that device. It is created on first use and is the same stream that the runtime API in the same process uses as the default stream for the same thread and device. No function returns its handle. Device memory allocation and free (ha_drv_malloc,ha_drv_malloc_3d,ha_drv_free) are not stream-ordered and ignore theirstreamargument. - Asynchronous execution model: memory copies and kernel launches are always asynchronous. A call returns
right after the op is enqueued; check completion with
ha_drv_wait(). An error raised during execution stays on the stream and is returned at the next wait. One exception: when a kernel's first launch finds that kernel's binary copy still in flight on another stream,ha_drv_kernel_launch()waits on the host until the copy finishes. - Reset invalidates handles: after a device reset (
ha_drv_reset()), every earlier child handle (streams, events, memory allocations, kernels) is invalid. Every child object except the device handle must be created again. - Do not mix with the runtime API: do not use the runtime API (
Ha*) and the driver API on the same device. The address, stream and event state that the runtime manages goes out of sync with driver API calls. For details, see the Driver API guide.