Environment Variables¶
The runtime reads environment variables exactly once, when configuration is first needed (the first Ha* or ha_drv_*
API call, or the first host memory allocation). Changing a value after that point has no effect, so set it before
launch (in the shell) or before the first Ha* API call.
Environment variables not listed in this document are not intended to be set, and incorrectly specified names do not produce a warning.
⚠️ Caution: Handling Invalid Environment Variable Values¶
- Partial application — Reading environment variables stops when an invalid value is encountered. Settings already applied are kept, and the rest remain at their defaults. The process continues.
- Read order — The order in which environment variables are read is not specified. If a value is invalid, it is not possible to predict which settings will take effect.
- Checking errors — If an error occurs while reading settings from environment variables, the runtime
writes an
Error-level log. Check this log first if a setting does not take effect. - Logger settings — The runtime applies logger settings after reading all environment variables. If
reading stops because of an invalid value,
HA_LOG_LEVEL,HA_LOG_PATH, andHA_LOG_OUTPUT_MODEare not applied to the logger.
1. How to Set¶
Environment variables can be set in the launch environment (CLI) or with setenv() in program initialization code.
Either way, they must be in place before the first Ha* call.
Set them in the terminal without changing code. This is the safest option because the values are guaranteed to be set before the process starts.
1 | |
To set them in code, do so before the first Ha* call so that the runtime reads them
correctly.
1 2 3 4 5 6 7 8 9 10 11 | |
As with C++, set them before the first hart API call. import hart
itself does not create the runtime yet, so setting them right after the import also works.
1 2 3 4 5 6 7 8 9 10 11 | |
2. Environment Variable Reference¶
Memory¶
| Variable | Value | Default | Effect |
|---|---|---|---|
HA_HUGE_POOL_THRESHOLD_SIZE_MB |
Integer (MB) | 0 (off) |
If greater than 0, enables the Huge tier in the Large pool and uses this size as the threshold. (Does not apply to the Small pool) |
HA_MAX_PAGE_WASTE_RATIO |
Float (0.0 to 1.0) |
0.0 |
Tail waste ratio allowed when selecting a page |
HA_SMALL_POOL_MIN_SPLIT_REMAINDER_KB |
Integer (KiB, 0 or greater) |
512 |
Minimum remainder when splitting a block in the Small pool. If the remainder would be smaller, the block is allocated whole without splitting. Values below 32 are raised to 32, and negative values are rejected as invalid |
HA_DEVICE_MEM_STATS_PRINT |
0 or 1 |
Value of HA_MEM_STATS_PRINT |
If 1, querying device memory statistics (HaDeviceMemGetStats(), ha_drv_device_mem_get_stats(), Python device_mem_get_stats()) also prints the same statistics to standard error |
Memory Copy¶
| Variable | Value | Default | Effect |
|---|---|---|---|
HA_MEMCPYND_PARALLEL_MIN_PER_THREAD |
Integer (bytes) | 2 MiB |
Minimum amount one worker must handle in the host↔host portion of HaMemCpyNd(). If the total is smaller, the copy runs sequentially |
HA_MEMCPYND_PARALLEL_MAX_THREADS |
Integer | 0 (auto) |
Upper bound on the number of workers for the same path. 0 determines it automatically from the number of physical cores, up to 8 |
HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES |
Integer (bytes), negative turns it off | 8 GiB |
When the total of unsynchronized asynchronous N-D copy staging buffers exceeds this value, a new staging copy first synchronizes its own stream and then proceeds. Nothing is rejected, so a wrong setting only changes throughput |
HA_MEMCPYND_STAGING_MAX_BYTES |
Integer (bytes), negative turns it off | Off | Upper bound on the total staging buffers of asynchronous N-D copies. Copies that exceed it are rejected with HaHostMemLimitExceeded. If set together with HA_HOST_MEM_MAX_BYTES, the lower one applies, and a value at or above HA_HOST_MEM_MAX_BYTES logs a warning that it has no effect. A value below an enabled HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES is a configuration error |
The defaults assume a typical server. In containers whose CPU is limited by cgroups or on asymmetric topologies, it is better
to set HA_MEMCPYND_PARALLEL_MAX_THREADS explicitly.
Host Memory¶
Applies to the per-process host memory manager. This manager is shared by the runtime API HaHostMemAlloc() and
driver API host memory, and the host
staging buffers of N-D copies are also allocated from it, so these limits apply to them too.
| Variable | Value | Default | Effect |
|---|---|---|---|
HA_HOST_MEM_MAX_BYTES |
Integer (bytes), negative turns it off | Off | Upper bound on host memory the process obtains from the OS. Includes both pool segments (including cached free blocks) and allocations that bypass the pool. An allocation that exceeds it is rejected with HaHostMemLimitExceeded if it still does not fit after free segments are released |
HA_HOST_MEM_STATS_PRINT |
0 or 1 |
Value of HA_MEM_STATS_PRINT |
If 1, querying host memory statistics (HaHostMemGetStats(), ha_drv_host_mem_get_stats(), Python host_mem_get_stats()) also prints the same statistics to standard error |
HA_MEM_STATS_PRINT |
0 or 1 |
0 (off) |
If 1, turns on both host and device memory statistics output. If HA_HOST_MEM_STATS_PRINT or HA_DEVICE_MEM_STATS_PRINT is set separately, that variable takes precedence for its kind |
Logging¶
| Variable | Value | Default | Effect |
|---|---|---|---|
HA_LOG_LEVEL |
Integer (0 to 6) |
2 (Info); 3 (Warn) in release builds |
Sets the log level (0: Trace, 1: Debug, 2: Info, 3: Warn, 4: Error, 5: Critical, 6: Off) |
HA_LOG_OUTPUT_MODE |
Integer (0 or 1) |
0 (console) |
Log output mode (0: console, 1: file) |
HA_LOG_PATH |
Path | ha_runtime.log |
Log file path (effective only when HA_LOG_OUTPUT_MODE=1) |
Minimum log level in release builds
Release builds do not support the Trace, Debug, or Info log levels (0 to 2). If
HA_LOG_LEVEL is set to one of these values, it is raised to Warn (3).
HA_LOG_PATH is used as the log file path only when HA_LOG_OUTPUT_MODE=1. If the specified log file does not exist,
a warning is logged. When file output is enabled, the required parent directories and log file are created.
See Error Handling for how to change logging settings in a program. If the program changes a logging setting after it was set through an environment variable, the new setting takes effect.
3. Settings Not Available Through Environment Variables¶
The settings below cannot be set through environment variables. Use the API.
- Current device:
HaSetDevice()/hart.set_device(). Set separately for each thread. - Sampling parameters:
HaSetSamplingParams()/hart.set_sampling_params() - TLB initialization:
HaInitTlb()/hart.init_tlb()