Error Codes
Every C++ entry point (other than helpers such as HaDataTypeBits() and the string conversions below) returns HaError. Codes are stable across releases, and a code is never
reused with a different meaning.
Classification and handling are described in Error Handling.
Encoding
The category is carried in the upper bits, so you can branch on the kind of failure without
listing every code.
| Category |
Encoding |
Value |
| Success |
0 |
0 |
| Common |
code |
1 – 65535 |
| Device |
(1 << 16) \| code |
0x1_0000 and above |
| Memory |
(2 << 16) \| code |
0x2_0000 and above |
| Kernel |
(3 << 16) \| code |
0x3_0000 and above |
| Stream |
(4 << 16) \| code |
0x4_0000 and above |
| Event |
(5 << 16) \| code |
0x5_0000 and above |
Common
| Code |
Name |
Cause |
Action |
0 |
HaSuccess |
— |
— |
1 |
HaInvalidArgument |
A device-independent argument is out of range or a null pointer |
Check the arguments against the signature |
2 |
HaNotSupported |
The API, option, or execution path is not supported |
Check the Support Matrix |
3 |
HaTimeout |
Did not complete within the time limit |
Check for a kernel that does not terminate. See Troubleshooting |
4 |
HaInternalError |
Unexpected runtime state |
This is a defect. Collect logs and report it |
5 |
HaUnknownError |
Unclassified failure |
This is a defect. Collect logs and report it |
Device
| Code |
Name |
Cause |
Action |
HaDeviceError \| 1 |
HaDeviceNotAvailable |
The device does not exist or cannot be opened |
Check that ha.ko is loaded and that /dev/ha* is accessible |
HaDeviceError \| 2 |
HaDeviceNotInitialized |
The device exists but is inactive (for example, not refreshed after HaResetAllDevices() on another thread). VMM: a mapping was called before HaVmmInitBlocks() |
Call HaSetDevice() again on that thread. For VMM, follow the call order |
HaDeviceError \| 3 |
HaDeviceNotReady |
Initialization, reset, or loading is in progress |
Retry after the in-progress operation finishes |
HaDeviceError \| 4 |
HaDeviceInvalidArgument |
Device ID out of range, a null pointer, or the calling thread has no current device at all (HaSetDevice() was never called) |
Validate the ID with HaGetDeviceCount(), or call HaSetDevice() on that thread first |
HaDeviceError \| 5 |
HaDeviceAlreadyInitialized |
Already initialized |
Not an error in most flows. Ignore it or restructure initialization |
HaDeviceError \| 6 |
HaDeviceOpenFailed |
The driver rejected to open the device |
Check device node permissions and whether another process holds the device |
HaDeviceError \| 7 |
HaDeviceCloseFailed |
Close failed |
Collect logs and report it |
HaDeviceError \| 8 |
HaDeviceResetFailed |
Reset failed |
Reinitialization at the driver level may be required |
HaDeviceError \| 10 |
HaDeviceUnsupported |
The device, version, or feature is not supported |
Check the Support Matrix |
HaDeviceError \| 11 |
HaDeviceRegisterSetFailed |
Setting a device register failed |
Check the paging configuration; the device often rejects it |
HaDeviceError \| 12 |
HaDeviceInvalidValue |
The device returned a value the runtime cannot interpret |
Collect logs and report it |
HaDeviceError \| 13 |
HaDeviceBusy |
The device is still in use. For example, ha_drv_deinit() was called while device handles remain open |
Close all handles with ha_drv_close() and call again |
Memory
| Code |
Name |
Cause |
Action |
HaMemoryError \| 1 |
HaMemoryInvalidAddress |
Host/device pointer mismatch or a null device pointer |
Check that the direction argument matches the pointers passed |
HaMemoryError \| 2 |
HaMemoryAlignmentError |
Alignment constraint violated |
Check the DRAM alignment rules in the Memory Model |
HaMemoryError \| 3 |
HaMemoryInvalidArgument |
Invalid size, null pointer, or layout rank/shape mismatch. VMM: the mapping's block_size is not 1, row_indices is missing or outside 0–1023, or pool_base is not 4 KiB aligned |
HaMemCpyNd() does not broadcast. Both sides must have the same rank and shape. For VMM, check the argument descriptions in the VMM API |
HaMemoryError \| 4 |
HaMemoryAllocationFailed |
Out of memory or no block satisfies the constraints. VMM: pool_bytes is smaller than the K+V pages of one request |
Allocate large buffers once at startup. See Troubleshooting. For VMM, enlarge the pool |
HaMemoryError \| 5 |
HaMemoryFreeFailed |
Free failed |
Check that the pointer came from an allocation and was not already freed |
HaMemoryError \| 6 |
HaMemoryCopyFailed |
Transfer failed |
Treat the destination as partially written |
HaMemoryError \| 7 |
HaMemCpyNotSupported |
Unsupported copy combination. For example, a device-to-device N-D transfer below the minimum size |
Route through the host, or use LCCL for collectives |
HaMemoryError \| 8 |
HaHostMemLimitExceeded |
A configured limit (HA_HOST_MEM_MAX_BYTES, HA_MEMCPYND_STAGING_MAX_BYTES) rejected a host memory allocation. System memory exhaustion is HaMemoryAllocationFailed |
Raise the limit in Environment Variables, or free host memory that is no longer in use |
Kernel
| Code |
Name |
Cause |
Action |
HaKernelError \| 1 |
HaKernelInvalidArgument |
The argument list does not fit the kernel (kind, count, or route), a moved-from argument list, or an invalid kernel binary or library data |
Compare the expected and passed layouts recorded in the log. For argument list rules, see Execution API |
HaKernelError \| 2 |
HaKernelUnsupported |
The kernel or execution path is not supported |
Check the Support Matrix |
HaKernelError \| 3 |
HaKernelExecutionFailed |
The kernel ran and failed, or a device fault occurred |
Device state is not guaranteed. Do not retry in place |
HaKernelError \| 4 |
HaKernelNotFound |
The kernel binary path does not resolve, or the kernel library has no kernel with that name |
Check the path relative to the process working directory. For library kernels, check the name |
HaKernelError \| 5 |
HaKernelInvalidHandle |
The kernel handle was released, invalidated by a device reset, or never loaded. Or a library or library kernel handle was not returned by HaLibraryLoadData() or HaLibraryGetKernel() (driver API: ha_drv_library_*) |
In the driver API, reload with ha_drv_kernel_load_from_file() or ha_drv_kernel_load_from_library(). Pass library handles exactly as issued |
HaKernelError \| 6 |
HaKernelNoBinaryForDevice |
The kernel library has no kernel binary for the chip generation of the launch device |
Rebuild the library to include that device version |
HaKernelError \| 7 |
HaKernelLoadFailed |
The device failed to load the kernel (for a reason other than running out of kernel memory) |
Check the device state. Running out of kernel memory is HaMemoryAllocationFailed |
Stream
| Code |
Name |
Cause |
Action |
HaStreamError \| 1 |
HaStreamInvalidHandle |
Unknown or stale stream handle |
A device reset invalidates streams |
HaStreamError \| 2 |
HaStreamInvalidArgument |
Invalid stream argument |
|
HaStreamError \| 3 |
HaStreamCreationFailed |
Creation failed |
The limit is 10 per device |
HaStreamError \| 4 |
HaStreamDestroyFailed |
Destruction failed |
Synchronize before destroying |
HaStreamError \| 5 |
HaStreamSyncFailed |
Synchronization failed |
Work on the stream failed. Check the preceding operation |
HaStreamError \| 6 |
HaStreamNotReady |
Not an error. HaStreamQuery() reports that work is in progress |
Poll again |
Event
| Code |
Name |
Cause |
Action |
HaEventError \| 1 |
HaEventInvalidHandle |
Unknown or stale event handle |
A device reset invalidates events |
HaEventError \| 2 |
HaEventInvalidArgument |
Invalid event argument |
|
HaEventError \| 3 |
HaEventCreationFailed |
Creation failed |
|
HaEventError \| 4 |
HaEventDestroyFailed |
Destruction failed |
Do not destroy an event a stream is waiting on |
HaEventError \| 5 |
HaEventNotRecorded |
Not an error. HaEventRecord() has never been called on this event |
Record before waiting or querying |
HaEventError \| 6 |
HaEventNotReady |
Not an error. HaEventQuery() reports that the event is incomplete |
Poll again |
Three codes are normal control flow
HaStreamNotReady, HaEventNotReady, and HaEventNotRecorded are values that query entry points use to report
state. A polling loop that treats every nonzero return as a fatal error stops on the first
iteration.
Error name strings
HaError is a bit-packed value, so its integer value is hard to interpret (e.g. err=131078). Get a string with the two
functions of the public header ha_error.h. Both are in the lpu::runtime namespace.
| Function |
Returns |
const char *HaErrorName(HaError err) |
The enumerator name (e.g. "HaMemoryCopyFailed"), stable enough for tests and log scrapers to match on. "HaUnrecognizedError" for a value outside the enum |
const char *HaErrorToString(HaError err) |
A human-readable description |
| #include "ha_error.h"
HaError err = HaMemCpy(dst, src, size, HaMemCpyDirection::HostToDevice);
if (err != HaError::HaSuccess) {
std::fprintf(stderr, "copy failed: %s\n", lpu::runtime::HaErrorName(err));
}
|
Python functions of the hart module raise RuntimeError on failure, with a message of the form <failed call>: <error name> (err=<integer value>).
See also