MUSA 环境变量参考

本文档详细介绍 MUSA Driver 支持的环境变量。这些变量与 CUDA 环境变量兼容，可从 CUDA 应用无缝迁移到 MUSA。

---

设备枚举和属性

MUSA_VISIBLE_DEVICES

指定应用程序可见的 GPU 设备。

值	说明
GPU 标识符的逗号分隔序列	整数索引或 UUID 字符串

详细描述： GPU 标识符可以是整数索引或 UUID 字符串。只有序列中存在的设备索引对 MUSA 应用程序可见，且按序列顺序枚举。

• 逗号分隔的整数索引：0,1,2
• UUID 字符串：GPU-8932f937,...
• 支持负索引：-1（无设备可见）

示例：

export MUSA_VISIBLE_DEVICES=0,2,3
export MUSA_VISIBLE_DEVICES=GPU-8932f937  # 使用 UUID
export MUSA_VISIBLE_DEVICES=-1  # 无设备可见

---

MUSA_MANAGED_FORCE_DEVICE_ALLOC

强制驱动将所有托管分配放置在设备内存中。

值	说明
0	默认行为
1	强制设备分配

示例：

export MUSA_MANAGED_FORCE_DEVICE_ALLOC=1

---

MUSA_DEVICE_ORDER

控制设备枚举顺序。

值	说明
FASTEST_FIRST	按计算能力枚举（默认）
PCI_BUS_ID	按 PCI 总线 ID 枚举

详细描述： FASTEST_FIRST 使用简单启发式方法按从快到慢的顺序枚举可用设备。PCI_BUS_ID 按 PCI 总线 ID 升序排列设备。

示例：

export MUSA_DEVICE_ORDER=PCI_BUS_ID

---

执行

MUSA_LAUNCH_BLOCKING

启用阻塞式内核启动。

值	说明
0	非阻塞（默认）
1	阻塞模式

详细描述： 禁用（设为 1）或启用（设为 0）异步内核启动。启用后，主机将等待内核完成。

示例：

export MUSA_LAUNCH_BLOCKING=1

---

模块加载

MUSA_MODULE_LOADING

指定应用程序的模块加载策略。

值	说明
DEFAULT	默认加载行为
EAGER	启动时加载所有模块
LAZY	按需加载模块

详细描述： 指定应用程序的模块加载模式。设为 EAGER 时，所有内核会在相应的 cuModuleLoad* API 调用时完全加载。设为 LAZY 时，加载特定内核会延迟到使用 cuModuleGetFunction API 调用提取 CUfunc 句柄时。默认行为为 EAGER。

示例：

export MUSA_MODULE_LOADING=LAZY

---

注意事项

1. 设置文件：环境变量也可以在应用程序目录中的 musaSettings.cfg 文件中设置。环境变量优先于设置文件值。

2. 持久性：环境变量仅影响当前会话。对于永久设置，请将它们添加到 shell 配置文件（例如 ~/.bashrc、~/.zshrc）。

3. 验证：无效值可能被忽略或导致意外行为。检查应用程序日志以获取验证警告。

4. UUID 支持：对于 MUSA_VISIBLE_DEVICES，UUID 字符串应遵循与 musa-smi 相同的格式，例如 GPU-8932f937-d72c-4106-c12f-20bd9faed9f6。为方便起见，可以使用缩写形式，只需指定足够的前缀位数即可唯一标识目标系统中的 GPU。