入门指南

1. PCIe 设备基本信息查询

• 为确保服务器和操作系统已经识别 MTT S 系列 GPU，在 Host 操作系统中输入 lspci -d 1ed5: 命令查询设备 ID

  # MTT S3000
  $ lspci -d 1ed5:
  03:00.0 3D controller: Moore Threads Technology Co.,Ltd MTT S3000 
  03:00.1 Multimedia audio controller: Moore Threads Technology Co.,Ltd MTT HDMI/DP Audio

  正常情况下，对应显卡的显示内容应该如上所示

2. vGPU 切分

vGPU 的切分支持两种方式

• mdevctl 工具
• 直接操作设备文件

两种方式的本质都是对设备文件进行操作以达到对 vGPU 设备管理的目的。MT vGPU 支持的显卡切分类型请见附录 MTT S 系列显卡支持的 vGPU 切分类型。

切分方式一：推荐使用 mdevctl 工具对显卡进行切分操作，使用mdevctl工具切分显卡的流程如下：

1. 查看 GPU PCI 设备 BDF 地址

   $ lspci -d 1ed5:
   03:00.0 3D controller: Moore Threads Technology Co.,Ltd MTT S3000

   03:00.0 为 GPU 的 BDF 地址

   $ virsh nodedev-list --cap pci| grep 03_00_0
   pci_0000_03_00_0

   完整的标识地址为 0000:03:00.0

2. 创建 vGPU

   $ mdevctl start -u c4f702ca-c69d-4d7d-a526-5fdcf78d3428 -p 0000:03:00.0 --type mtgpu-1101

   • c4f702ca-c69d-4d7d-a526-5fdcf78d3428是 UUID，是 vGPU 设备的唯一标识；此 ID 可以是固定的 ID，也可以通过 uuidgen 工具生成：uuidgen => xxxxxxx
   • -p GPU PCI 设备的 BDF 地址
   • -type vGPU 切分类型

3. 查看创建的 vGPU 设备

   $ mdevctl list
   c4f702ca-c69d-4d7d-a526-5fdcf78d3428 0000:03:00.0 mtgpu-1101

切分方式 2: 操作设备文件

1. 查看并操作文件设备

   $ find /sys/ -name mdev_supported_types
   /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0/0000:02:00.0/0000:03:00.0
   
   $ echo c4f702ca-c69d-4d7d-a526-5fdcf78d3428 > /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0/0000:02:00.0/0000:03:00.0/mdev_supported_types/mtgpu-1101/create

   设备文件实际地址可按照这种方式去定位，/sys/class/mdev_bus/domain\:bus\:slot.function/mdev_supported_types/ ，上面的地址 0000:03:00.0，则 domain 为 0000、bus 为 03、slot 为 00、funtion 为 0

2. 查看切分出的 vGPU 设备

   $ ls /sys/bus/mdev/devices/
   c4f702ca-c69d-4d7d-a526-5fdcf78d3428

3. 常用操作

3.1 vGPU 查询

方法 1，使用 mdevctl 工具

$ mdevctl list
c4f702ca-c69d-4d7d-a526-5fdcf78d3428 0000:03:00.0 mtgpu-1101

方法 2，操作设备文件

$ ls /sys/bus/mdev/devices/
c4f702ca-c69d-4d7d-a526-5fdcf78d3428

3.2 vGPU 删除

方法 1，使用 mdevctl 工具

$ mdevctl stop -u c4f702ca-c69d-4d7d-a526-5fdcf78d3428

方法 2，操作设备文件

$ echo 1 > /sys/bus/mdev/devices/c4f702ca-c69d-4d7d-a526-5fdcf78d3428/remove

3.3 调度方式配置

摩尔线程的 vGPU 支持两种调度方式：性能最优调度方式和时间切片调度方式。

注意：默认配置为性能最优调度方式

性能最优调度方式 (Best-effort scheduling)

性能最优调度方式，遵循以下规则

• 跨多个 vGPU 来平衡性能
• 每个 vGPU 独占整个 GPU 处理周期。

处理期间不会被其他 vGPU 打断，只有在周期完成后，其他 vGPU 才会继续使用。在某些极端的场景下，某个 vGPU 渲染任务多且重，有可能会导致其他 vGPU 无法获得时间片，从而导致经常挂起的状态。

时间切片调度方式 (Time-sliced scheduling)

在此种调度方式下，激活的 vGPU 会等分当前 GPU 的算力，即 equal share mode

配置 MT vGPU 调度方式

调度方式通过安装驱动时进行修改。

1. 在 /etc/modprobe.d 目录下创建 mtgpu.conf文件。
2. 在配置文件中，赋予参数mtgpu_vgpu_scheduling_policy不同值（0 或 1）来选择调度方式。其中，0 表示使用 Best Effort Scheduling；1 表示使用 Time Sliced Scheduling。

参考如下配置：

option mtgpu mtgpu_vgpu_scheduling_policy=0

说明：如果选择了 Time Sliced Scheduling， mtgpu_vgpu_time_sliced_value 的值会决定时分复用的时间，以毫秒为单位。

3. 重新加载 mtgpu 驱动或重启服务器生效

3.4 限制最大分辨率

mtgpu-1101 类型默认可以支持 4K 显示，由于 4K 对 GPU 资源消耗较多，并发时可能会影响其他用户的体验，因此 mtgpu-1101 类型 4k 显示功能可以在加载驱动阶段禁用

1. 在 /etc/modprobe.d 目录下创建 mtgpu.conf文件，在配置文件中添加

options mtgpu vgpu_1g_support_4k=0

2. 重新加载 mtgpu 驱动或重启服务器生效

3.5 禁用 Guest 驱动自动升级

Host 驱动升级后 Guest 默认会收到升级提醒，可以通过配置文件关闭升级提醒

1. 在 /etc/modprobe.d 目录下创建 mtgpu.conf文件，在配置文件中添加

options mtgpu vgpu_upgrade_mode=0

2. 重新加载 mtgpu 驱动或重启服务器生效

说明：2.5.0 升级到 2.5.6 仍然需要删除 /var/local/mthreads/wddm_driver.zip 关闭 Guest 升级服务，2.5.6 升级到更高版本时可以通 vgpu_upgrade_mode=0 配置关闭

3.6 使用 MT Virtual Display

查看 MT-virt 显示器标号，例如 MT-virt 显示器为 2 号显示器，屏幕设置成仅在 2 上显示

3.7 在多显示适配器下手动选择程序 GPU 加速

在单 GPU 模式且没有其他显示设备的场景下，所有应用都会默认使用摩尔线程 vGPU 作为加速，在有其他显示设备时需要设置为仅在 MT Virtual Display 上显示。

查看 MT-virt 显示器标号，例如 MT-virt 显示器为 2 号显示器，屏幕设置成仅在 2 上显示

4. 驱动卸载

1. Host 驱动卸载

关闭所有使用 vGPU 设备的虚拟机，

$ rmmod mtgpu
$ rpm -e mtvgpu

2. Windows Guest 驱动卸载

   打开控制面板>程序>卸载程序，卸载 PES Control Center

   

3. Linux Guest 驱动卸载

   以 root 权限运行

   $ dpkg -P musa

   重启虚拟机

5. MT GPU 管理工具使用

通过摩尔线程 GPU 管理接口工具 mthreads-gmi 可以实现 GPU 和 vGPU 管理和监控。

显示帮助信息

$ mthreads-gmi --help

监控 GPU 整卡概括信息

$ mthreads-gmi -cf

监控 vGPU 解码详细信息

$ mthreads-gmi vgpu -ds

监控 vGPU 编码详细信息

$ mthreads-gmi vgpu -es

监控 vGPU 使用率

$ mthreads-gmi vgpu -u

监控 vGPU 详细信息

$ mthreads-gmi vgpu -q

更多命令，参见 mthreads-gmi 命令参考。

6. 驱动升级

摩尔线程 MT vGPU Guest 驱动支持驱动自动升级，Host 驱动升级后，Guest 在开机后会受到升级提醒，按照提示操作 Guest 驱动可以完成升级

驱动升级流程如下

1. Host 驱动升级

关闭所有虚拟机，卸载 Host 驱动

$ rmmod mtgpu
$ rpm -e mtvgpu

安装新版本 Host 驱动，加载内核驱动

$ rpm -ivh xxx_xxx_v1_3_mtvgpu_2.9.1-000_amd64.rpm
$ modprobe mtgpu

2. Guest 自动升级

Guest 驱动升级支持两种方式，Host 驱动升级完成后 Guest 驱动会收到升级提醒，根据升级提醒升级.

Guest 收到升级提醒

提示用户关闭应用程序

升级完成后提醒用户重启操作系统

重启后驱动升级完成

7. 驱动热升级

针对线上服务器需长时间稳定运行的需求，常规 host 驱动版本升级需关闭虚拟机，会造成业务中断，而热升级方案可在几乎不中断业务的前提下完成驱动升级。需要注意的是，MT vGPU 2.9.1 及以上版本才开始支持该驱动热升级功能，具体可通过热升级升级至哪些版本，可参考 Release Note 中的说明。

使用方法:

rpm -Uvh xxx_xxx_v1_3_mtvgpu_2.9.1-000_amd64.rpm

8. vGPU 虚拟机热迁移

vGPU 热迁移可以将一个带有 MT vGPU 设备的虚拟机，从一台服务器迁移到另外一台服务器，迁移过程中几乎不会造成服务中断或停机，对于已配置 MT vGPU 的虚拟机，其 vGPU 会随虚拟机一同迁移到另一台主机的 MT GPU 上，两台主机上的 MT GPU 及 MT vGPU 必须为同一型号。

热迁移由内核、libvirt、qemu、GPU 驱动共同协作完成，因此对内核，libvirt、qemu 版本有特定要求

• 内核版本：openEuler 24.03(6.6.0), Ubuntu 24.04 (6.8.0)
• QEMU 版本：8.2.0
• Libvirt: 9.10.0

基于 KVM hypervisor 的 Linux 系统热迁移使用方法:

1. 将虚拟机的最大停机时间设置为长于完成迁移所需的时间。

   若虚拟机负载较高，迁移可能无法在默认的最大停机时间内完成。为确保虚拟机迁移顺利完成，需保证最大停机时间超过实际迁移所需时间。

   命令：

   virsh migrate-setmaxdowntime --domain $name --downtime $time

   其中：

   • $name：本地主机上待迁移的虚拟机名称。
   • $time：虚拟机的最大停机时间（单位：毫秒）。

   示例：将本地主机上名为 guestvm 的虚拟机的最大停机时间设置为 20 秒（20,000 毫秒）。

   virsh migrate-setmaxdowntime --domain guestvm --downtime 20000

2. 运行以下 virsh 迁移命令：

   virsh migrate --live $name $destination-url --verbose

   $name 指本地主机上待迁移的虚拟机名称。

   $destination-url（目标 URL）

   指与待迁移虚拟机所指向的远程主机之间的连接 URL。例如，若要通过 SSH 隧道将虚拟机迁移到 IPv4 地址为 192.168.1.2 的远程主机的系统连接，可将 destination-url 指定为qemu+ssh://root@192.168.1.2/system。

   以下示例为：通过 SSH 隧道将本地主机上名为 guestvm 的虚拟机，迁移到 IPv4 地址为 192.0.2.12 的远程主机的系统连接。

   virsh migrate --live guestvm qemu+ssh://root@192.168.1.2/system --verbose

更多详细信息参考 Red Hat Enterprise Linux 9

9. MT DirectStream samples 使用说明

用例说明：

文件名称	功能说明
AppEncD3D11.exe	从本地文件读取 YUV 数据进行编码，码流写入指定的文件。
AppEncD3D11Perf.exe	衡量 FPS 中的编码性能 (一次性读入文件，所以 YUV 文件不宜过大)，码流不写入文件。
AppEncDDA.exe	捕获桌面，并对捕获的图像进行编码 (用于 virtual display 场景)，码流写入文件 DDABitStream_x_x.h264（微软抓屏接口）。
AppEncMTCapture.exe	摩尔线程私有桌面抓屏编码方案，功能同 AppEncDDA.exe，效率更高，功能集成参考 mtencode api 手册或参考 sample code

使用方法:

1. 准备一个 NV12 文件 (用于 AppEncD3D11.exe 或 AppEncD3D11Perf.exe)

2. 测试用例命令如下:

   使用 YUV 文件编码 h.264 码流

   AppEncD3D11.exe -i 1920x1080_nv12.yuv -s 1920x1080 -src_fmt nv12 -bf 0 -rc cqp -constqp 20 -fps 25 -gop 30 -frames 100 -o out.h264

   性能测试

   AppEncD3D11Perf.exe -i 1920x1080_nv12.yuv -s 1920x1080 -src_fmt nv12 -bf 0 -rc cqp -constqp 20 -fps 25 -gop 30 -frames 50000 -o out-cqp.h264

   抓取屏幕并编码成 h.264 码流

   AppEncDDA.exe

参数说明：

AppEncD3D11.exe/AppEncD3D11Perf.exe Options:

-i           Input file path
-o           Output file path
-s           Input resolution in this form: WxH
-src_fmt     input file pixel format(nv12, bgra)
-frames      encode frame number
-profile     H264: auto baseline main high
-fps         Frame rate
-gop         Length of GOP (Group of Pictures)
-bf          Number of consecutive B-frames
-rc          Rate control mode: cqp cbr
-bitrate     Average bit rate, can be in unit of 1, K, M
-constqp     QP value for cqp rate control mode

AppEncDDA.exe Options:
-frames      encode frame number

10. MT API 自定义分辨率用例使用说明

custom_resolution_x64.exe 用于设置屏幕自定义分辨率，分辨率支持范围 640x360---当前规格支持最大分辨率，使用方法如下

custom_resolution_x64.exe -t 0 1920 1080 60 -s 0 1920 1080 60

参数说明

-t 0 1920 1080 60，为在 0 号显示器上尝试创建 1920 x 1080 60 Hz 属性的显示器

-s 0 1920 1080 60，为在 0 号显示器上保存 1920 x 1080 60 Hz 属性显示器的设置

附录

MTT S 系列显卡支持的 vGPU 切分类型

Type-ID	Type-vRAM	虚拟机内 vRAM 大小	最大分辨率	建议最大分辨率	虚拟显示器数量	S3000/S3000E 可用数量
mtgpu-1100	1024MB	854MB	1920x1200	1920x1080	1	32
mtgpu-1101	1024MB	982MB	4096x2160	2560x1440	2	28
mtgpu-1102	2048MB	1734MB	4096x2160	3840x2160	2	16
mtgpu-1104	4096MB	3478MB	4096x2160	3840x2160	2	8
mtgpu-1108	8192MB	6966MB	4096x2160	3840x2160	2	4
mtgpu-1116	16384MB	14870MB	4096x2160	3840x2160	2	2
mtgpu-1132	32768MB	30334MB	7680×4320	3840x2160	2	1