已弃用功能

通常，功能加入 QEMU 后会长期受到支持。如果需要移除，会先列在本节。该功能在宣布弃用的版本及之后一个版本中仍可使用；经过这两个版本后，便可能被移除。启动 QEMU 或通过监视器启用弃用功能时，也可能在控制台显示警告，但并非强制要求。

带版本号的机器类型采用例外规则，其支持期限为 6 年，即 18 个 QEMU 版本，而非无限期支持。发布满 3 年（9 个版本）后自动标记弃用，再过 3 年删除。建议只为现有虚拟机部署的迁入和保存状态恢复使用弃用机器类型，并在合适的维护窗口升级到较新类型。新部署的虚拟机应只使用未弃用的机器类型，强烈建议选择最新版本。不带版本号的机器类型遵循普通功能的弃用规则。

以下列出当前所有标记为弃用的功能。

系统模拟器命令行参数

简写布尔选项（自 6.0 起）

share=on 和 share=off 等布尔选项过去可以简写为 share 和 noshare。这种形式现已弃用，会产生警告。

socket 字符设备的 `delay` 选项（自 6.0 起）

nodelay 简写布尔选项应替换为 nodelay=on，而非 delay=off。

通过 `arg=<string>` 传递插件参数（自 6.1 起）

通过 arg= 传递 TCG 插件参数是多余的，还会降低命令行可读性，尤其当参数本身也是名称和值组成时，例如 -plugin plugin_name,arg="arg_name=arg_value"。因此不再需要这层 arg 包装。单词参数会被视为简写布尔值，以 arg_name=on 传给插件。但简写布尔形式也已弃用，推荐显式使用完整的 arg_name=on。

`-name` 的 `debug-threads` 选项（自 11.0 起）

-name 的 debug-threads 已被忽略。凡平台支持线程命名，QEMU 都无条件启用。

`-mon` 选项（自 11.1 起）

当 -qmp 或 -monitor 快捷选项不够灵活时， -mon 曾是创建监视器对象的通用机制。监视器已转换为 QOM 对象，因此 -mon mode=readline 由 -object monitor-hmp 取代，-mon mode=control 由 -object monitor-qmp 取代。快捷选项没有弃用，只有 -mon 被弃用。

QEMU 机器协议（QMP）命令

`blockdev-open-tray`、`blockdev-close-tray` 的 `device` 参数（自 2.8 起）

改用 id 参数。

`eject` 的 `device` 参数（自 2.8 起）

改用 id 参数。

`blockdev-change-medium` 的 `device` 参数（自 2.8 起）

改用 id 参数。

`block_set_io_throttle` 的 `device` 参数（自 2.8 起）

id 参数是替代方式。

`blockdev-add` 的空字符串 `backing` 参数（自 2.10 起）

改用参数值 null。

`block-commit` 的 `base` 和 `top` 参数（自 3.1 起）

分别改用 base-node 和 top-node。

`nbd-server-add` 和 `nbd-server-remove` （自 5.2 起）

改用更通用的 block-export-add 和 block-export-del。原 nbd-server-add 使用单个 bitmap，新 block-export-add 使用 bitmaps 列表。

`query-qmp-schema` 返回值中的 `values` 成员（自 6.2 起）

返回元素的元类型为 enum 时，values 成员已弃用，应使用 members。

`drive-backup` （自 6.2 起）

改用 blockdev-backup 与 blockdev-add。主要变化是将备份目标的创建和打开拆分为独立、显式的步骤。 blockdev-backup 的参数大多与 drive-backup 相同，但移除了 format 和 mode，改由显式调用 blockdev-create 和 blockdev-add 完成。详见在线块设备操作。

`block-job-pause` （自 10.1 起）

改用 job-pause。区别仅在于，job-pause 失败时总是报告 GenericError，而 block-job-pause 在找不到块作业时报告 DeviceNotActive。

`block-job-resume` （自 10.1 起）

改用 job-resume。区别仅在于，job-resume 失败时总是报告 GenericError，而 block-job-resume 在找不到块作业时报告 DeviceNotActive。

`block-job-complete` （自 10.1 起）

改用 job-complete。区别仅在于，job-complete 失败时总是报告 GenericError，而 block-job-complete 在找不到块作业时报告 DeviceNotActive。

`block-job-dismiss` （自 10.1 起）

改用 job-dismiss。

`block-job-finalize` （自 10.1 起）

改用 job-finalize。

`query-kvm` （自 11.0 起）

改用 query-accelerators。

人机监视器协议（HMP）命令

`wavcapture` （自 10.2 起）

wavcapture 已弃用，将在未来版本移除。

改用 -audiodev wav 或宿主音频系统捕获音频。

`stopcapture` （自 10.2 起）

stopcapture 已弃用，将在未来版本移除。

`info` 的 `capture` 参数（自 10.2 起）

info capture 已弃用，将在未来版本移除。

宿主架构

TCI 默认不启用 TCG 插件支持（自 9.2 起）

虽然 TCG 解释器可以解释插件使用的 TCG 操作，但速度太慢，不适合实际插桩。实现差异还会导致内存插桩等行为出现异常。

系统模拟器 CPU

`power5+` 和 `power7+` CPU 名称（自 9.0 起）

QEMU 对象模型已不允许设备及 CPU 名称包含加号。 power5+、power5+_v2.1、power7+ 和 power7+_v2.1 暂时仍通过别名支持，但为保持一致，未来也将移除。请使用 power5p_v2.1 和 power7p_v2.1。

`Sun-UltraSparc-IIIi+` 和 `Sun-UltraSparc-IV+` CPU 名称（自 9.1 起）

QEMU 对象模型已不允许设备及 CPU 名称包含加号。 Sun-UltraSparc-IIIi+ 和 Sun-UltraSparc-IV+ 暂时仍通过兼容处理支持，但未来将为保持一致而移除。请使用 Sun-UltraSparc-IIIi-plus 和 Sun-UltraSparc-IV-plus。

系统模拟器机器

带版本号的机器类型（aarch64、arm、i386、m68k、ppc64、s390x、x86_64）

按照机器类型弃用规则，版本不高于 8.1.0 的所有机器类型均已弃用。

Arm `virt` 机器的 `dtb-kaslr-seed` 属性（自 7.1 起）

virt 开发板的 dtb-kaslr-seed 已弃用，改用 dtb-randomness。新名称更准确地反映该属性会影响设备树中的全部随机数据，而不只是 kaslr-seed 节点。

RISC-V Shakti 机器（自 11.1 起）

RISC-V shakti_c 自 2021 年以来没有实质性贡献，目前无人维护。由于似乎没有用户，计划将其移除。

机器的 `memory-encryption` 属性（自 11.1 起）

改用 confidential-guest-support。 memory-encryption 是 QEMU 早期的内存加密实现，现已被功能更全面的 confidential-guest-support 对象取代。

后端选项

对非持久后备文件使用 pmem=on（自 6.1 起）

此选项用于模拟 NVDIMM 设备所使用的 memory-backend-file。如果后备文件不支持 DAX，或所在文件系统不支持持久内存直接映射，启用 memory-backend-file.pmem 不安全，宿主崩溃时可能丢失或损坏数据。可选择：

修改虚拟机配置，设置 pmem=off，继续使用非 DAX 存储上的后备文件，将其作为没有持久性保证的模拟 NVDIMM。

将后备文件移到 NVDIMM 存储，并保持 pmem=on，获得持久性保证。

使用外部 DH（Diffie-Hellman）参数文件（自 10.2 起）

从 dh-params.pem 加载外部 Diffie-Hellman 参数的功能已弃用，未来将直接移除，不提供替代选项。没有该文件时，DH 参数会按 RFC7919 自动协商。

设备选项

模拟设备选项

`-device nvme-ns,eui64-default=on|off` （自 7.1 起）

QEMU 6.1、6.2 和 7.0 中，nvme-ns 生成的 EUI-64 标识符不具备全局唯一性。如果需要 EUI-64，用户必须通过 nvme-ns 的 eui64 参数显式设置。

`-device nvme,use-intel-id=on|off` （自 7.1 起）

nvme 最初使用了未正式分配的 Intel PCI 厂商/设备 ID 组合。从 5.2 起，控制器使用正式分配的 ID，因此弃用 use-intel-id 机器兼容参数。

`-device cxl-type3,memdev=xxxx` （自 8.0 起）

cxl-type3 最初只使用单个内存后端。加入易失性内存支持后，需要区分持久和易失内存后端，因此弃用 memdev，改用 persistent-memdev。

首字母为大写 Z 的 RISC-V CPU 属性（自 8.2 起）

这些属性过去被错误地以大写 Z 添加，从 8.2 起全部弃用。后来加入了对应的小写名称，今后应采用这种格式。

使用旧属性时会显示警告，建议切换到对应的稳定名称：

"Zifencei" 改为 "zifencei"。
"Zicsr" 改为 "zicsr"。
"Zihintntl" 改为 "zihintntl"。
"Zihintpause" 改为 "zihintpause"。
"Zawrs" 改为 "zawrs"。
"Zfa" 改为 "zfa"。
"Zfh" 改为 "zfh"。
"Zfhmin" 改为 "zfhmin"。
"Zve32f" 改为 "zve32f"。
"Zve64f" 改为 "zve64f"。
"Zve64d" 改为 "zve64d"。

块设备选项

`"backing": ""` （自 2.12 起）

要防止 QEMU 自动打开镜像的后备链，应使用 "backing": null。

`rbd` 键值对编码文件名：`""` （自 3.1 起）

rbd 应像其他块驱动一样，通过运行时选项配置。旧键值对文件名解析仅用于打开采用旧后备文件格式的镜像，这些镜像应更新为当前格式。

旧编码示例：:

json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}

转换为当前支持的格式后：:

json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}

`iscsi,password=xxx` （自 8.0 起）

通过命令行的 password 选项明文指定 iSCSI 密码不安全。应改用 password-secret，引用 --object secret... 对象，通过文件或加密方式提供密码。

字符设备选项

`memory` 后端（自 9.0 起）

memory 是 ringbuf 的弃用别名。

CPU 设备属性

RISC-V CPU 的 `pmu-num=n` （自 8.2 起）

为支持更灵活的计数器配置，改用 pmu-mask。若计数器集合连续，可以通过 ((2 ^ n) - 1) << 3 计算掩码。最低三位必须保持为零。

x86 的 `pcommit` （自 9.1 起）

PCOMMIT 从未出现在实际处理器中。直到 QEMU 9.0，TCG 将其实现为空操作，但仅对 -cpu max 生效，而 max 不保证跨版本迁移兼容性。

RISC-V CPU 的 `debug=true|false` （自 11.0 起）

从 QEMU 10.1 起，此选项只是 sdtrig 扩展的别名。建议直接启用或禁用 sdtrig，不再使用 debug。

linux-user 模式 CPU

Arm CPU 的 OABI 和 NWFPE 支持

32 位 Arm Linux 曾有两个主要 ABI：早期 OABI 和较新的 EABI。 GCC 4.7 将 OABI 标记为过时，GCC 4.8（2013 年发布）移除了支持。 Linux 内核中的 OABI 兼容处理 OABI_COMPAT 通常默认关闭，且不兼容 Thumb2 内核。发行版至少十五年前就已停止支持 OABI。

32 位 Arm 最初的浮点协处理器是 FPA11。虽然许多 CPU 没有它，但 OABI 的浮点参数传递方式依赖它，因此 Linux 内核通过 FPE_NWFPE 模拟， QEMU 也相应支持。GCC 4.8 同样移除了 FPA11 支持。

QEMU 的 NWFPE 代码陈旧、未经测试且不具备线程安全性，OABI 也早已过时。因此二者均被弃用，将在未来版本移除。

向后兼容性

CPU 模型的可运行性保证（自 4.1 起）

过去，QEMU 不会通过修改已有 CPU 模型，为虚拟机增加宿主软硬件要求。管理软件因此可以安全地改变现有虚拟机的机器类型而不引入新要求，这称为可运行性保证。但它也妨碍 CPU 模型加入漏洞缓解措施，使客户机在默认配置下仍面临漏洞风险。

已有 CPU 模型不再享有这种保证。需要可运行性保证的管理软件，必须使用 query-cpu-definitions 返回的 alias-of 字段解析 CPU 模型别名。

仍保持这些保证的版本中，该命令返回的已有模型别名指向不会破坏保证的版本，具体为模型的第 1 版。未来版本会根据机器类型将别名指向较新的 CPU 模型版本，因此管理软件必须在启动虚拟机前解析别名。

x86 isapc 开发板使用现代 x86 CPU（自 10.2 起）

isapc 表示历史上的 x86 ISA PC，面向较旧的 32 位 x86 CPU，默认采用 486。过去可以指定较新的 CPU，包括 -cpu host 或 -cpu max，即使这些特性与预期客户机系统不兼容，这样做也没有实际意义。

如果请求的 CPU 不属于 486、athlon、kvm32、pentium、 pentium2、pentium3 或 qemu32，当前会显示警告，未来版本将拒绝这些 CPU。

已弃用功能

系统模拟器命令行参数

简写布尔选项（自 6.0 起）

socket 字符设备的 delay 选项（自 6.0 起）

通过 arg=<string> 传递插件参数（自 6.1 起）

-name 的 debug-threads 选项（自 11.0 起）

-mon 选项（自 11.1 起）

QEMU 机器协议（QMP）命令

blockdev-open-tray、blockdev-close-tray 的 device 参数（自 2.8 起）

eject 的 device 参数（自 2.8 起）

blockdev-change-medium 的 device 参数（自 2.8 起）

block_set_io_throttle 的 device 参数（自 2.8 起）

blockdev-add 的空字符串 backing 参数（自 2.10 起）

block-commit 的 base 和 top 参数（自 3.1 起）

nbd-server-add 和 nbd-server-remove （自 5.2 起）

query-qmp-schema 返回值中的 values 成员（自 6.2 起）

drive-backup （自 6.2 起）

block-job-pause （自 10.1 起）

block-job-resume （自 10.1 起）

block-job-complete （自 10.1 起）

block-job-dismiss （自 10.1 起）

block-job-finalize （自 10.1 起）

query-kvm （自 11.0 起）

人机监视器协议（HMP）命令

wavcapture （自 10.2 起）

stopcapture （自 10.2 起）

info 的 capture 参数（自 10.2 起）

宿主架构

TCI 默认不启用 TCG 插件支持（自 9.2 起）

系统模拟器 CPU

power5+ 和 power7+ CPU 名称（自 9.0 起）

Sun-UltraSparc-IIIi+ 和 Sun-UltraSparc-IV+ CPU 名称（自 9.1 起）

系统模拟器机器

带版本号的机器类型（aarch64、arm、i386、m68k、ppc64、s390x、x86_64）

Arm virt 机器的 dtb-kaslr-seed 属性（自 7.1 起）

RISC-V Shakti 机器（自 11.1 起）

机器的 memory-encryption 属性（自 11.1 起）

后端选项

对非持久后备文件使用 pmem=on（自 6.1 起）

使用外部 DH（Diffie-Hellman）参数文件（自 10.2 起）

设备选项

模拟设备选项

-device nvme-ns,eui64-default=on|off （自 7.1 起）

-device nvme,use-intel-id=on|off （自 7.1 起）

-device cxl-type3,memdev=xxxx （自 8.0 起）

首字母为大写 Z 的 RISC-V CPU 属性（自 8.2 起）

块设备选项

"backing": "" （自 2.12 起）

rbd 键值对编码文件名："" （自 3.1 起）

iscsi,password=xxx （自 8.0 起）

字符设备选项

memory 后端（自 9.0 起）

CPU 设备属性

RISC-V CPU 的 pmu-num=n （自 8.2 起）

x86 的 pcommit （自 9.1 起）

RISC-V CPU 的 debug=true|false （自 11.0 起）

linux-user 模式 CPU

Arm CPU 的 OABI 和 NWFPE 支持

向后兼容性

CPU 模型的可运行性保证（自 4.1 起）

x86 isapc 开发板使用现代 x86 CPU（自 10.2 起）

socket 字符设备的 `delay` 选项（自 6.0 起）

通过 `arg=<string>` 传递插件参数（自 6.1 起）

`-name` 的 `debug-threads` 选项（自 11.0 起）

`-mon` 选项（自 11.1 起）

`blockdev-open-tray`、`blockdev-close-tray` 的 `device` 参数（自 2.8 起）

`eject` 的 `device` 参数（自 2.8 起）

`blockdev-change-medium` 的 `device` 参数（自 2.8 起）

`block_set_io_throttle` 的 `device` 参数（自 2.8 起）

`blockdev-add` 的空字符串 `backing` 参数（自 2.10 起）

`block-commit` 的 `base` 和 `top` 参数（自 3.1 起）

`nbd-server-add` 和 `nbd-server-remove` （自 5.2 起）

`query-qmp-schema` 返回值中的 `values` 成员（自 6.2 起）

`drive-backup` （自 6.2 起）

`block-job-pause` （自 10.1 起）

`block-job-resume` （自 10.1 起）

`block-job-complete` （自 10.1 起）

`block-job-dismiss` （自 10.1 起）

`block-job-finalize` （自 10.1 起）

`query-kvm` （自 11.0 起）

`wavcapture` （自 10.2 起）

`stopcapture` （自 10.2 起）

`info` 的 `capture` 参数（自 10.2 起）

`power5+` 和 `power7+` CPU 名称（自 9.0 起）

`Sun-UltraSparc-IIIi+` 和 `Sun-UltraSparc-IV+` CPU 名称（自 9.1 起）

Arm `virt` 机器的 `dtb-kaslr-seed` 属性（自 7.1 起）

机器的 `memory-encryption` 属性（自 11.1 起）

`-device nvme-ns,eui64-default=on|off` （自 7.1 起）

`-device nvme,use-intel-id=on|off` （自 7.1 起）

`-device cxl-type3,memdev=xxxx` （自 8.0 起）

`"backing": ""` （自 2.12 起）

`rbd` 键值对编码文件名：`""` （自 3.1 起）

`iscsi,password=xxx` （自 8.0 起）

`memory` 后端（自 9.0 起）

RISC-V CPU 的 `pmu-num=n` （自 8.2 起）

x86 的 `pcommit` （自 9.1 起）

RISC-V CPU 的 `debug=true|false` （自 11.0 起）