> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VM 管理 — 基于 KVM 的 RT

## **使用 Libvirt 和 Virsh 进行 VM 管理**

Qualcomm 平台使用 **Libvirt** 和 **Virsh** 管理客户机 VM 的生命周期。domain XML 文件定义 VM 配置，并传递给 `virsh` 以创建、启动和管理 VM。

***

### 设置步骤

#### 启用 libvirt 守护进程

```bash theme={null}
systemctl enable --now virtqemud virtqemud.socket
systemctl enable --now virtnetworkd virtnetworkd.socket
```

#### 将防火墙后端切换为 nftables

`ip_tables` 模块与 `PREEMPT_RT` 不兼容（其依赖项 `NETFILTER_XTABLES_LEGACY` 要求 `!PREEMPT_RT`）。请改用 `nftables`：

```
# /etc/libvirt/network.conf
firewall_backend = "nftables"
```

#### 确保构建中包含 iproute2 和 `act_csum.ko`

* 将 `iproute2` 添加到镜像配方中（提供 nftables 所需的 `tc` 工具）
* 在内核配置中启用 `CONFIG_NET_ACT_CSUM=m`（提供 `act_csum.ko`）

#### 在 QEMU 构建中启用 vhost-net

在 `meta-qcom-distro/conf/distro/include/qcom-base.inc` 中将 `vhost` 添加到 QEMU 的 PACKAGECONFIG：

```diff theme={null}
-PACKAGECONFIG:append:pn-qemu = " pixman virtfs vnc-jpeg vnc-sasl"
+PACKAGECONFIG:append:pn-qemu = " pixman virtfs vnc-jpeg vnc-sasl vhost"
```

#### 启动默认网络并定义 VM

```bash theme={null}
virsh net-start default
virsh net-list --all

# Copy kernel Image and rootfs to /var/rtvm/ and /var/hkvm/ first
virsh define rt-vm.xml
virsh define hk-vm.xml

virsh start rt-vm
virsh start hk-vm
virsh list --all
```

***

### 已知问题及解决方法

> [accordion] 问题 1 — 无法连接到 hypervisor（virsh net-start default）
>
> **原因：** `virtqemud` 和 `virtnetworkd` 守护进程及套接字未运行。
>
> **解决方法：**
>
> ```bash theme={null}
> systemctl start virtqemud virtqemud.socket
> systemctl enable virtqemud virtqemud.socket
> systemctl start virtnetworkd virtnetworkd.socket
> systemctl enable virtnetworkd virtnetworkd.socket
> ```

> [accordion] 问题 2 — 找不到 ip\_tables 模块（与 PREEMPT\_RT 不兼容）
>
> **原因：** `NETFILTER_XTABLES_LEGACY` 依赖于 `!PREEMPT_RT`，因此无法在 RT 内核上构建 `ip_tables.ko`。
>
> **解决方法：** 在 `/etc/libvirt/network.conf` 中将 libvirt 网络防火墙后端设置为 `nftables`：
>
> ```
> firewall_backend = "nftables"
> ```

> [accordion] 问题 3 — 切换到 nftables 后找不到 'tc'
>
> **原因：** 构建中未包含 `iproute2`（提供 `tc`）和 `act_csum.ko`。
>
> **解决方法：** 将 `iproute2` 添加到镜像配方中，并在内核配置中启用 `CONFIG_NET_ACT_CSUM=m`。

> [accordion] 问题 4 — 未编译 vhost-net 支持（virsh start 失败）
>
> **原因：** QEMU 未启用 `vhost` PACKAGECONFIG 选项。
>
> **解决方法：** 在 `qcom-base.inc` 中将 `vhost` 添加到 `PACKAGECONFIG:append:pn-qemu`（参见上文设置步骤 4）。

***

### domain XML 示例文件

我们提供了两个参考 domain XML 文件：一个用于实时客户机 VM，另一个用于非 RT 的 housekeeping 客户机 VM。

| 文件 | VM 名称 | 用途 |
| - | - | - |
| `rt-vm.xml` | `rt-vm` | RT 客户机 — vCPU 绑定到 RT 隔离 CPU，透传 SR-IOV VF |
| `hk-vm.xml` | `hk-vm` | 非 RT 客户机 — vCPU 绑定到 housekeeping CPU，无设备透传 |

#### `rt-vm.xml` — 关键配置

| 设置 | 值 | 用途 |
| - | - | - |
| vCPU | 6 个（绑定到 CPU 2–7） | 与内核命令行中的 RT 隔离 CPU 集合一致 |
| 内存 | 4 GB（锁定） | `<memoryBacking><locked/>` 可防止换出和延迟尖峰 |
| 模拟器绑定 | CPU 0 | 将 QEMU 模拟器线程保持在 housekeeping CPU 上 |
| RT 调度 | `SCHED_FIFO`，vCPU 1–5 | 确定性的 vCPU 线程调度 |
| SR-IOV VF | 10 个 Intel X550 VF | 通过 `<hostdev>` 配合 `virtio-iommu-pci` 透传 |
| 客户机命令行 | `isolcpus=1-5 rcu_nocbs=1-5 irqaffinity=0` | 在客户机内部应用的 RT 调优 |

> [accordion] 查看完整的 rt-vm.xml
>
> ```xml theme={null}
> <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
>   <name>rt-vm</name>
>   <memory unit='KiB'>4194304</memory>
>   <currentMemory unit='KiB'>4194304</currentMemory>
>   <memoryBacking>
>     <locked/>
>   </memoryBacking>
>   <vcpu placement='static'>6</vcpu>
>   <os>
>     <type arch='aarch64' machine='virt-6.2'>hvm</type>
>     <kernel>/var/rtvm/Image</kernel>
>     <cmdline>console=hvc0 root=/dev/vda rcupdate.rcu_expedited=1 rcu_nocbs=1-5 isolcpus=1-5 irqaffinity=0 skew_tick=1</cmdline>
>     <boot dev='hd'/>
>   </os>
>   <features>
>     <gic version='3'/>
>   </features>
>   <cpu mode='host-passthrough' check='none'/>
>   <devices>
>     <emulator>/usr/bin/qemu-system-aarch64</emulator>
>     <disk type="file" device="disk">
>       <driver name="qemu" type="raw"/>
>       <source file="/var/rtvm/rootfs.img"/>
>       <target dev="vda" bus="virtio"/>
>     </disk>
>     <interface type='network'>
>       <source network='default' bridge='virbr0'/>
>       <model type='virtio'/>
>     </interface>
>     <console type='pty'>
>       <target type='virtio' port='0'/>
>     </console>
>     <!-- VF 1–10: Intel X550 SR-IOV virtual functions passed through -->
>     <hostdev mode='subsystem' type='pci' managed='yes'>
>       <source><address domain='0x0001' bus='0x02' slot='0x10' function='0x0'/></source>
>     </hostdev>
>     <!-- ... VF 2–10 follow the same pattern ... -->
>     <filesystem type='mount' accessmode='mapped' fmode='644' dmode='755'>
>       <source dir='/mnt/vmshare'/>
>       <target dir='hostshare'/>
>     </filesystem>
>   </devices>
>   <cputune>
>     <vcpupin vcpu='0' cpuset='2'/>
>     <vcpupin vcpu='1' cpuset='3'/>
>     <vcpupin vcpu='2' cpuset='4'/>
>     <vcpupin vcpu='3' cpuset='5'/>
>     <vcpupin vcpu='4' cpuset='6'/>
>     <vcpupin vcpu='5' cpuset='7'/>
>     <realtime>
>       <period>1000000</period>
>       <runtime>950000</runtime>
>     </realtime>
>     <vcpusched vcpus='1-5' scheduler='fifo' priority='1'/>
>     <emulatorpin cpuset='0'/>
>   </cputune>
>   <qemu:commandline>
>     <qemu:arg value="-device"/>
>     <qemu:arg value="virtio-iommu-pci,bus=pcie.0,addr=0x3"/>
>   </qemu:commandline>
> </domain>
> ```

#### `hk-vm.xml` — 关键配置

| 设置 | 值 | 用途 |
| - | - | - |
| vCPU | 2 个（绑定到 CPU 0–1） | housekeeping CPU，与 RT 隔离集合分离 |
| 内存 | 2 GB | 通用用途，无需锁定内存 |
| 无 `<hostdev>` / SR-IOV | — | 非 RT 工作负载，无直接设备透传 |
| 无 `<realtime>` / `<vcpusched>` | — | 默认 CFS 调度器 |

> [accordion] 查看完整的 hk-vm.xml
>
> ```xml theme={null}
> <domain type='kvm'>
>   <name>hk-vm</name>
>   <memory unit='KiB'>2097152</memory>
>   <currentMemory unit='KiB'>2097152</currentMemory>
>   <vcpu placement='static'>2</vcpu>
>   <os>
>     <type arch='aarch64' machine='virt-6.2'>hvm</type>
>     <kernel>/var/hkvm/Image</kernel>
>     <cmdline>console=hvc0 root=/dev/vda</cmdline>
>     <boot dev='hd'/>
>   </os>
>   <features>
>     <gic version='3'/>
>   </features>
>   <cpu mode='host-passthrough' check='none'/>
>   <devices>
>     <emulator>/usr/bin/qemu-system-aarch64</emulator>
>     <disk type="file" device="disk">
>       <driver name="qemu" type="raw"/>
>       <source file="/var/hkvm/rootfs.img"/>
>       <target dev="vda" bus="virtio"/>
>     </disk>
>     <interface type='network'>
>       <source network='default' bridge='virbr0'/>
>       <model type='virtio'/>
>     </interface>
>     <console type='pty'>
>       <target type='virtio' port='0'/>
>     </console>
>   </devices>
>   <cputune>
>     <vcpupin vcpu='0' cpuset='0'/>
>     <vcpupin vcpu='1' cpuset='1'/>
>     <emulatorpin cpuset='0'/>
>   </cputune>
> </domain>
> ```

***

> [card] [NIC 与 SR-IOV](https://dragonwingdocs-staging.qualcomm.com/zh/Suites/Industrial-Edge-Suite/rt-with-kvm-nic-sriov.md)
>
> Intel X550 内核配置与 IOMMU-map 设置

> [card] [基于 KVM 的 RT](https://dragonwingdocs-staging.qualcomm.com/zh/Suites/Industrial-Edge-Suite/rt-with-kvm.md)
>
> 返回概览
