Skip to content

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
#include "ha_driver_api.h"

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.

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
find_package(hart REQUIRED COMPONENTS hw)
target_link_libraries(your_target PRIVATE hart::ha_umd_core)

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.

  1. 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 with ha_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_count and ha_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; and ha_drv_launch_args_set_*, which only change an existing argument list.
  2. 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 their stream argument.
  3. 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.
  4. 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.
  5. 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.