API Reference¶
hart provides the same runtime through two interfaces. The C++ API is the primary definition; the Python API is a binding of it.
| Interface | How to access | Reference |
|---|---|---|
| C++ | #include "ha_runtime_api.h" |
C++ API — generated from the headers |
| Python | import hart |
Python API |
This reference describes the functions, parameters, and return values of the C++ and Python APIs. For API behavior and usage, including execution and synchronization, see the Programming Guide.
Name Mapping¶
A Python name is the C++ name with the Ha prefix removed, converted to snake_case.
| C++ | Python |
|---|---|
HaGetDeviceCount() |
get_device_count() |
HaSetDevice() |
set_device() |
HaMemAlloc() |
mem_alloc() |
HaMemCpyAsync() |
mem_cpy_async() |
HaLaunchKernel(binary_path, …) |
launch_kernel_with_binary_path() |
HaLaunchKernel(kernel, …) |
launch_kernel_with_handle() |
HaStreamSynchronize() |
stream_synchronize() |
Exceptions are listed in Differences from the C++ API.
The Python Weight Converter API is provided by the hart.weight_converter module and does not follow the naming rule
above. For example, HaWeightConvert() corresponds to convert(), and HaWeightGetConvertedSize() corresponds to
get_converted_size(). The HaWeight prefix is also dropped from type names (HaWeightTensor → Tensor). The
debugging function show() is available only in Python. For details, see
Python Weight Converter API.
Public Headers¶
Everything outside runtime/shared/public/ is internal and may change without notice.
These are the headers you include directly.
| Header | Contents |
|---|---|
ha_runtime_api.h |
All Ha* entry points except HaVmm* |
ha_driver_api.h |
Driver API (ha_drv_*) entry points. See Driver API |
ha_driver_types.h |
Driver API types (HaDrv*) and the kernel argument list HaLaunchArgs. Included by ha_driver_api.h and ha_runtime_api.h |
ha_types.h |
HaDevicePtr, HaLayout, HaTensorKind, HaDataType, HaDeviceAttr, HaDeviceVersion, memory statistics structs, TLB configuration structs, stream, event, library, and kernel handles, and the kernel library format (HaLibraryData). Includes ha_error_code.h |
ha_error_code.h |
Error code HaError |
ha_error.h |
HaErrorName() and HaErrorToString(), which turn a HaError into a string. See Error Codes |
ha_callback_params.h |
Argument structs for API call instrumentation. See Callback Params |
ha_vmm.h |
VMM entry points and block pool types. See VMM |
weight_converter/ha_weight_converter.h, weight_converter/ha_weight_converter_types.h |
Weight conversion entry points and types. See Weight Converter |
Entry Points by Area¶
| Area | Entry points |
|---|---|
| Device | HaGetDeviceCount, HaSetDevice, HaGetDevice, HaGetDeviceAttribute, HaDeviceSynchronize, HaResetDevice, HaResetAllDevices, HaIsRuntimeConstructed |
| Memory | HaMemAlloc, HaMemAlloc3D, HaMemAllocAsync, HaMemFree, HaMemFreeAsync, HaMemCpy, HaMemCpyAsync, HaMemCpyNd, HaMemCpyNdAsync, HaMemLoadFileAsync, HaMemDumpForEachChannel, HaBuildDeviceTensorLayout, HaDeviceMemGetStats, HaDeviceMemResetPeakStats, HaDeviceMemTrim, HaHostMemAlloc, HaHostMemFree, HaHostMemGetStats, HaHostMemResetPeakStats, HaHostMemTrim |
| Execution | HaLibraryLoadData, HaLibraryGetKernel, HaLaunchKernel, HaLaunchKernelAsync, HaLaunchArgsAddTensor, HaLaunchArgsAddScalar, HaLaunchArgsAddArray, HaLaunchArgsSetTensor, HaLaunchArgsSetScalarBits, HaLaunchArgsSetArray |
| Stream | HaStreamCreate, HaStreamDestroy, HaStreamSynchronize, HaStreamQuery, HaStreamWaitEvent, HaStreamGetDevice |
| Event | HaEventCreate, HaEventDestroy, HaEventRecord, HaEventSynchronize, HaEventQuery |
| TLB | HaInitTlb, HaAllocTlbPage, HaDeallocTlbPage, HaConfigureTlb, HaSetPageTableRange, HaFlushTlb |
| VMM | HaVmmReserveBlocks, HaVmmAllocatePool, HaVmmInitBlocks, HaVmmMapBlocksBatchFromPool, HaVmmMapBlocksBatchFromPools, HaVmmUnmapBlocksBatchFromPool, HaVmmFreePool, HaVmmDeinit |
| Sampling | HaSetSamplingParams, HaSetSamplingParamsAsync |
| Weight conversion | HaWeightGetConvertedSize, HaWeightConvert |
Common Semantics¶
Properties that apply across the API. Per-entry-point details are in the generated reference.
| Property | Value |
|---|---|
| Return type | HaError for every C++ entry point. Outputs are passed through pointer parameters |
| Outputs on failure | Not written. Initialize them yourself |
| Exceptions | Do not cross the C++ boundary. Python raises RuntimeError. The only C++ exceptions come from the HaLaunchArgs constructor (std::bad_alloc when memory is short) and the Weight Converter HaWeightTensor constructor |
| Device selection | Per-thread current device. Most entry points have no device argument. The Weight Converter does not use a device |
| Default stream | HA_STREAM_DEFAULT (nullptr, 0 in Python) is the per-thread default stream |
| Stream limit | 10 per device |
| Asynchronous completion | Only enqueues. Check completion with a stream or event |
| Runtime creation | Created lazily on the first call. Only HaIsRuntimeConstructed() does not create it |