NVML API 参考指南 :: GPU 部署和管理文档

< 上一个 | 下一个 >

NVML API 参考指南 (PDF) - vR570 (更旧版本) - 最近更新于 2025 年 1 月 29 日 - 发送反馈

4.25. vGPU 迁移

本章介绍与 vGPU 迁移相关的操作。

枚举

enum nvmlVgpuPgpuCompatibilityLimitCode_t

vGPU-pGPU 兼容性限制代码

值

NVML_VGPU_COMPATIBILITY_LIMIT_NONE = 0x0: 兼容性不受限制。
NVML_VGPU_COMPATIBILITY_LIMIT_HOST_DRIVER = 0x1: 兼容性受主机驱动程序版本限制。
NVML_VGPU_COMPATIBILITY_LIMIT_GUEST_DRIVER = 0x2: 兼容性受客户机驱动程序版本限制。
NVML_VGPU_COMPATIBILITY_LIMIT_GPU = 0x4: 兼容性受 GPU 硬件限制。
NVML_VGPU_COMPATIBILITY_LIMIT_OTHER = 0x80000000: 兼容性受未定义因素限制。

enum nvmlVgpuVmCompatibility_t

vGPU VM 兼容性代码

值

NVML_VGPU_VM_COMPATIBILITY_NONE = 0x0: vGPU 不可运行
NVML_VGPU_VM_COMPATIBILITY_COLD = 0x1: vGPU 可从冷启动/断电状态 (ACPI S5) 运行
NVML_VGPU_VM_COMPATIBILITY_HIBERNATE = 0x2: vGPU 可从休眠状态 (ACPI S4) 运行
NVML_VGPU_VM_COMPATIBILITY_SLEEP = 0x4: vGPU 可从睡眠状态 (ACPI S3) 运行
NVML_VGPU_VM_COMPATIBILITY_LIVE = 0x8: vGPU 可从活动/暂停状态 (ACPI S0) 运行

函数

nvmlReturn_t nvmlDeviceGetPgpuMetadataString ( nvmlDevice_t device, char* pgpuMetadata, unsigned int* bufferSize )

参数

device: 目标设备的标识符
pgpuMetadata: 指向调用者提供的缓冲区的指针，pgpuMetadata 将写入到该缓冲区中
bufferSize: 指向 pgpuMetadata 缓冲区大小的指针

返回值

NVML_SUCCESS GPU 元数据结构已成功返回
NVML_ERROR_INSUFFICIENT_SIZE pgpuMetadata 缓冲区太小，所需大小在 bufferSize 中返回
NVML_ERROR_INVALID_ARGUMENT 如果 bufferSize 为 NULL 或设备无效；如果 pgpuMetadata 为 NULL 且 bufferSize 的值不为 0。
NVML_ERROR_NOT_SUPPORTED 如果系统不支持 vGPU
NVML_ERROR_UNKNOWN 任何意外错误

描述

以 ASCII 编码的字符串格式返回设备指示的物理 GPU 的属性。

调用者通过 pgpuMetadata 传入缓冲区，并在 bufferSize 中指定缓冲区的大小。如果字符串太大而无法放入提供的缓冲区，则该函数返回 NVML_ERROR_INSUFFICIENT_SIZE，并在 bufferSize 中返回所需的大小。

nvmlReturn_t nvmlDeviceGetVgpuMetadata ( nvmlDevice_t device, nvmlVgpuPgpuMetadata_t* pgpuMetadata, unsigned int* bufferSize )

参数

device: 目标设备的标识符
pgpuMetadata: 指向调用者提供的缓冲区的指针，pgpuMetadata 将写入到该缓冲区中
bufferSize: 指向 pgpuMetadata 缓冲区大小的指针

返回值

NVML_SUCCESS GPU 元数据结构已成功返回
NVML_ERROR_INSUFFICIENT_SIZE pgpuMetadata 缓冲区太小，所需大小在 bufferSize 中返回
NVML_ERROR_INVALID_ARGUMENT 如果 bufferSize 为 NULL 或设备无效；如果 pgpuMetadata 为 NULL 且 bufferSize 的值不为 0。
NVML_ERROR_NOT_SUPPORTED 系统不支持 vGPU
NVML_ERROR_UNKNOWN 任何意外错误

描述

返回设备指示的物理 GPU 的 vGPU 元数据结构。该结构包含有关 GPU 和当前安装的 NVIDIA 主机驱动程序版本的信息，以及包含内部状态的不透明数据部分。

调用者通过 pgpuMetadata 传入缓冲区，并在 bufferSize 中指定缓冲区的大小。如果 pgpuMetadata 结构太大而无法放入提供的缓冲区，则该函数返回 NVML_ERROR_INSUFFICIENT_SIZE，并在 bufferSize 中返回所需的大小。

nvmlReturn_t nvmlDeviceGetVgpuSchedulerCapabilities ( nvmlDevice_t device, nvmlVgpuSchedulerCapabilities_t* pCapabilities )

参数

device: 目标设备的标识符
pCapabilities: 写入 pCapabilities 的引用

返回值

NVML_SUCCESS vGPU 调度器功能已成功获取
NVML_ERROR_INVALID_ARGUMENT 如果 pCapabilities 为 NULL 或设备无效
NVML_ERROR_NOT_SUPPORTED 当前状态不支持 API 或设备不在 vGPU 主机模式下
NVML_ERROR_UNKNOWN 任何意外错误

描述

返回 vGPU 调度器功能。nvmlVgpuSchedulerCapabilities_t 中返回的受支持 vGPU 调度器列表来自 NVML_VGPU_SCHEDULER_POLICY_*。如果引擎类型为 Graphics，则此列表枚举了受支持的调度器策略。nvmlVgpuSchedulerCapabilities_t 中的其他值也适用于引擎类型为 Graphics 的情况。对于其他引擎类型，它是 BEST EFFORT 策略。如果 ARR 受支持且已启用，则调度频率和平均因子适用，否则 timeSlice 适用。

适用于 Pascal 或更新的完全支持的设备。

nvmlReturn_t nvmlDeviceGetVgpuSchedulerLog ( nvmlDevice_t device, nvmlVgpuSchedulerLog_t* pSchedulerLog )

参数

device: 目标设备的标识符
pSchedulerLog: 写入 pSchedulerLog 的引用

返回值

NVML_SUCCESS vGPU 调度器日志已成功获取
NVML_ERROR_INVALID_ARGUMENT 如果 pSchedulerLog 为 NULL 或设备无效
NVML_ERROR_NOT_SUPPORTED 当前状态不支持 API 或设备不在 vGPU 主机模式下
NVML_ERROR_UNKNOWN 任何意外错误

描述

返回 vGPU 软件调度器日志。pSchedulerLog 指向调用者分配的结构体以包含日志。返回的元素数量永远不会超过 NVML_SCHEDULER_SW_MAX_LOG_ENTRIES。

要获取完整日志，请至少每秒调用该函数 5 次。

适用于 Pascal 或更新的完全支持的设备。

nvmlReturn_t nvmlDeviceGetVgpuSchedulerState ( nvmlDevice_t device, nvmlVgpuSchedulerGetState_t* pSchedulerState )

参数

device: 目标设备的标识符
pSchedulerState: 返回 pSchedulerState 的引用

返回值

NVML_SUCCESS vGPU 调度器状态已成功获取
NVML_ERROR_INVALID_ARGUMENT 如果 pSchedulerState 为 NULL 或设备无效
NVML_ERROR_NOT_SUPPORTED 当前状态不支持 API 或设备不在 vGPU 主机模式下
NVML_ERROR_UNKNOWN 任何意外错误

描述

返回 vGPU 调度器状态。如果设置了 BEST EFFORT 策略，则 nvmlVgpuSchedulerGetState_t 中返回的信息不相关。

适用于 Pascal 或更新的完全支持的设备。

nvmlReturn_t nvmlDeviceSetVgpuSchedulerState ( nvmlDevice_t device, nvmlVgpuSchedulerSetState_t* pSchedulerState )

参数

device: 目标设备的标识符
pSchedulerState: 要设置的 vGPU pSchedulerState

返回值

NVML_SUCCESS vGPU 调度器状态已成功设置
NVML_ERROR_INVALID_ARGUMENT 如果 pSchedulerState 为 NULL 或设备无效
NVML_ERROR_RESET_REQUIRED 如果设置 pSchedulerState 失败并出现致命错误，则需要重启才能从该错误中恢复。
NVML_ERROR_NOT_SUPPORTED 当前状态不支持 API 或设备不在 vGPU 主机模式下，或者设备上当前存在任何 vGPU 实例
NVML_ERROR_UNKNOWN 任何意外错误

描述

设置 vGPU 调度器状态。

适用于 Pascal 或更新的完全支持的设备。

调度器状态更改不会在模块加载/卸载之间持久存在。仅当没有 VM 运行时，才允许设置调度器状态和参数。在 nvmlVgpuSchedulerSetState_t 中，如果启用 enableARRMode，则提供 avgFactorForARR 和 frequency 作为输入。如果禁用 enableARRMode，则提供 timeslice 作为输入。

nvmlReturn_t nvmlGetVgpuCompatibility ( nvmlVgpuMetadata_t* vgpuMetadata, nvmlVgpuPgpuMetadata_t* pgpuMetadata, nvmlVgpuPgpuCompatibility_t* compatibilityInfo )

参数

vgpuMetadata: 指向调用者提供的 vGPU 元数据结构的指针
pgpuMetadata: 指向调用者提供的 GPU 元数据结构的指针
compatibilityInfo: 指向调用者提供的缓冲区以保存兼容性信息的指针

返回值

NVML_SUCCESS vGPU 元数据结构已成功返回
NVML_ERROR_INVALID_ARGUMENT 如果 vgpuMetadata 或 pgpuMetadata 或 bufferSize 为 NULL
NVML_ERROR_UNKNOWN 任何意外错误

描述

接受从 nvmlVgpuInstanceGetMetadata() 读取的 vGPU 实例元数据结构，以及从 nvmlDeviceGetVgpuMetadata() 读取的物理 GPU 的 vGPU 元数据结构，并返回 vGPU 实例和物理 GPU 的兼容性信息。

调用者通过 compatibilityInfo 传入缓冲区，兼容性信息结构将写入到该缓冲区中。该结构定义了 vGPU/VM 可以在物理 GPU 上启动的状态。如果 vGPU/VM 与物理 GPU 的兼容性受到限制，则限制代码指示限制兼容性的因素。（有关详细信息，请参阅 nvmlVgpuPgpuCompatibilityLimitCode_t）。

注意：vGPU 兼容性不考虑可能限制系统启动给定 vGPU 或关联 VM 的动态容量条件。

nvmlReturn_t nvmlGetVgpuVersion ( nvmlVgpuVersion_t* supported, nvmlVgpuVersion_t* current )

参数

supported: 指向结构的指针，NVIDIA vGPU 管理器支持的预设 vGPU 版本范围将写入到该结构中
current: 指向结构的指针，管理员设置的受支持 vGPU 版本范围将写入到该结构中

返回值

NVML_SUCCESS vGPU 版本范围结构已成功获取。
NVML_ERROR_NOT_SUPPORTED 不支持该 API。
NVML_ERROR_INVALID_ARGUMENT supported 参数或 current 参数为 NULL。
NVML_ERROR_UNKNOWN 获取数据时发生错误。

描述

查询受支持 vGPU 版本的范围。

此函数获取为 NVIDIA vGPU 管理器预设的受支持 vGPU 版本的线性范围以及管理员设置的范围。如果预设范围未被 nvmlSetVgpuVersion 覆盖，则两个范围相同。

调用者传递指向以下 nvmlVgpuVersion_t 结构的指针，NVIDIA vGPU 管理器会将范围写入到这些结构中：1. supported 结构，表示 NVIDIA vGPU 管理器支持的预设 vGPU 版本范围。2. current 结构，表示管理员设置的受支持 vGPU 版本范围。默认情况下，此范围与预设范围相同。

nvmlReturn_t nvmlSetVgpuVersion ( nvmlVgpuVersion_t* vgpuVersion )

参数

vgpuVersion: 指向调用者提供的受支持 vGPU 版本范围的指针。

返回值

NVML_SUCCESS 受支持 vGPU 版本的预设范围已成功覆盖。
NVML_ERROR_NOT_SUPPORTED 不支持该 API。
NVML_ERROR_IN_USE 该范围未被覆盖，因为主机上正在运行 VM。
NVML_ERROR_INVALID_ARGUMENT vgpuVersion 参数指定的范围超出了 NVIDIA vGPU 管理器支持的范围，或者 vgpuVersion 为 NULL。

描述

使用管理员设置的范围覆盖 NVIDIA vGPU 管理器支持的 vGPU 版本的预设范围。

此函数使用管理员设置的受支持 vGPU 版本范围配置 NVIDIA vGPU 管理器。此范围必须是 NVIDIA vGPU 管理器支持的预设范围的子集。管理员设置的自定义范围优先于预设范围，并通告给客户机 VM 以协商 vGPU 版本。请参阅 nvmlGetVgpuVersion 了解有关如何查询受支持的预设版本范围的详细信息。

此函数接受指向 vGPU 版本范围结构 nvmlVgpuVersion_t 的指针作为输入，以覆盖 NVIDIA vGPU 管理器支持的预设 vGPU 版本范围。

在主机系统重启或驱动程序重新加载后，受支持版本的范围将恢复为 NVIDIA vGPU 管理器的预设范围。

注意

1. 管理员设置的范围必须是 NVIDIA vGPU 管理器支持的预设范围的子集。否则，将返回错误。2. 如果受支持的客户机驱动程序版本的范围与管理员设置的范围不重叠，则客户机驱动程序无法加载。3. 如果受支持的客户机驱动程序版本的范围与管理员设置的范围重叠，则客户机驱动程序将加载协商的 vGPU 版本，该版本是重叠范围中的最大值。4. 调用此函数时，主机上不得运行任何 VM。如果主机上正在运行 VM，则对该函数的调用将失败。

nvmlReturn_t nvmlVgpuInstanceGetMetadata ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuMetadata_t* vgpuMetadata, unsigned int* bufferSize )

参数

vgpuInstance: vGPU 实例句柄
vgpuMetadata: 指向调用者提供的缓冲区的指针，vGPU 元数据将写入到该缓冲区中
bufferSize: vgpuMetadata 缓冲区的大小

返回值

NVML_SUCCESS vGPU 元数据结构已成功返回
NVML_ERROR_INSUFFICIENT_SIZE vgpuMetadata 缓冲区太小，所需大小在 bufferSize 中返回
NVML_ERROR_INVALID_ARGUMENT 如果 bufferSize 为 NULL 或 vgpuInstance 为 0；如果 vgpuMetadata 为 NULL 且 bufferSize 的值不为 0。
NVML_ERROR_NOT_FOUND 如果 vgpuInstance 与系统上有效的活动 vGPU 实例不匹配
NVML_ERROR_UNKNOWN 任何意外错误

描述

返回正在运行的 vGPU 的 vGPU 元数据结构。该结构包含有关 vGPU 及其关联 VM 的信息，例如当前安装的 NVIDIA 客户机驱动程序版本、主机驱动程序版本以及包含内部状态的不透明数据部分。

nvmlVgpuInstanceGetMetadata() 可以随时为 vGPU 实例调用。返回的结构中的某些字段取决于从客户机 VM 获取的信息，客户机 VM 可能尚未达到可以提供该信息的状态。这些依赖字段的当前状态反映在 info 结构的 nvmlVgpuGuestInfoState_t 字段中。

VMM 可以选择读取并保存 vGPU 的 VM 信息作为与 VM 关联的持久元数据，并在为 VM 的后续实例创建 vGPU 时将其提供给虚拟 GPU 管理器。

调用者通过 vgpuMetadata 传入缓冲区，并在 bufferSize 中指定缓冲区的大小。如果 vGPU 元数据结构太大而无法放入提供的缓冲区，则该函数返回 NVML_ERROR_INSUFFICIENT_SIZE，并在 bufferSize 中返回所需的大小。

< 上一个 | 下一个 >

NVML API 参考指南 (PDF) - vR570 (更旧版本) - 最近更新于 2025 年 1 月 29 日 - 发送反馈