Re: [PATCH docs 2/4] qm_memory: expand qm_memory_encryption documentation to include Intel TDX

[Dominik Csapak <d.csapak@proxmox.com>]

two comments inline, but maybe someone who has more looked into tdx
could also verify the content here (@markus?)

aside from the comments, looks good to me


On 7/8/26 3:05 PM, Elias Huhsovitz wrote:
> The pve-manager provides a help-button in the Intel TDX edit window, but
> there was no documentation regarding this.
> 
> Now includes basic information about Intel Trust Domain Extensions
> (TDX).
> 
> Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
> ---
>   qm.adoc | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 154 insertions(+)
> 
> diff --git a/qm.adoc b/qm.adoc
> index 8213758..cf82ad1 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -926,6 +926,160 @@ Links:
>   * https://documentation.suse.com/sles/15-SP7/single-html/SLES-amd-sev/article-amd-sev.html
>   * https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf[SEV Secure Nested Paging Firmware ABI Specification]
>   
> +[[qm_memory_encryption_tdx]]
> +Intel TDX
> +^^^^^^^^^
> +
> +Intel Trust Domain Extensions (TDX) protect guest VM memory and CPU state
> +from the host hypervisor. TDX uses Intel Multi-Key Total Memory Encryption
> +(MKTME) to provide per-VM memory encryption and introduces a CPU-isolated
> +module that manages the creation and execution of protected VMs (called Trust
> +Domains, or TDs).
> +
> +*Host Requirements:*
> +
> +* 4th Generation Intel Xeon Scalable processor (Codename: Sapphire Rapids)
> +  or newer. TDX is a hardware feature introduced with Sapphire Rapids and is
> +  not available on earlier Xeon generations.
> +  See https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[Intel — Xeon processors with TDX support].
> +* Enable TDX in the BIOS/UEFI settings. The kernel assumes the TDX module
> +  is loaded by the BIOS at boot.
> +  See https://docs.kernel.org/arch/x86/tdx.html#tdx-host-kernel-support[TDX host kernel support]
> +* A host kernel with TDX support. The kernel detects TDX by detecting TDX
> +  private KeyIDs configured by the BIOS during https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[early boot].
> +
> +*Notes:*
> +
> +* Add `nohibernate` to the kernel command line if hibernation support is
> +  compiled in. TDX cannot survive S3 (suspend-to-RAM) or S4 (hibernation)
> +  power states — the hardware resets and disables TDX completely when the
> +  platform enters these states.
> +  See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[Interaction vs S3 and deeper states]
> +* TDX module initialization
> +  https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[consumes approximately 1/256th of system RAM] for
> +  the Physical Address Metadata Table (PAMT).
> +* The TDX module is initialized https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[on demand] (when the first TDX guest is
> +  created), not at boot time.
> +
> +*Verify Intel TDX is Enabled on Host:*
> +
> +To https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[check if TDX is enabled on the host], search for `tdx` in `dmesg`.
> +If the BIOS has enabled TDX and the TDX module was successfully initialized,
> +the output should look like this:
> +
> +----
> +# dmesg | grep -i tdx
> +[...] virt/tdx: BIOS enabled: private KeyID range [64, 128)
> +[...] virt/tdx: 1050644 KB allocated for PAMT
> +[...] virt/tdx: module initialized
> +----
> +
> +If the TDX module is not loaded by the BIOS, dmesg will show:
> +
> +----
> +[...] virt/tdx: module not loaded
> +----
> +
> +If TDX initialization fails because hibernation is enabled in the kernel:
> +
> +----
> +[...] virt/tdx: initialization failed: Hibernation support is enabled
> +----
> +
> +The current TDX module version can be https://docs.kernel.org/arch/x86/tdx.html#how-to-update-the-tdx-module[checked at runtime]:
> +
> +----
> +# cat /sys/devices/faux/tdx_host/version
> +----
> ++
> +(If this path does not exist, the TDX module has not been initialized yet.)
> +
> +*Guest Requirements:*
> +
> +* https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[Trust Domain Virtual Firmware (TDVF)].
> +  TDVF is a TDX-enabled build of OVMF
> +  that provides TD services to boot the guest OS. Standard OVMF without TDX
> +  support cannot be used. TDVF is loaded via the `-bios` option because TDX
> +  does not support readonly memslots, so TDVF cannot be mapped as a pflash
> +  device.
> +* The guest operating system must contain https://docs.kernel.org/arch/x86/tdx.html#tdx-guest-support[TDX guest support].
> +  For Linux, this
> +  means a kernel with TDX guest support enabled, which sets up a #VE
> +  (Virtualization Exception) handler and shared-memory infrastructure at
> +  boot.
> +* The `kernel-irqchip` must be set to `split`. QEMU sets this
> +  https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[automatically]
> +  when launching a TDX guest if the setting is left on its default `auto`
> +  value.
> +* Advisable to use Q35
> +
> +*Limitations:*
> +
> +* Windows guests are not supported.
> +  See https://pve.proxmox.com/wiki/Roadmap[Proxmox VE Roadmap]
> +* Live migration is currently unsupported.
> +  See https://www.qemu.org/docs/master/system/i386/tdx.html#live-migration[QEMU — Live Migration] and https://pve.proxmox.com/wiki/Roadmap[PVE Roadmap]
> +* PCI passthrough to TDX guests is limited. Device MMIO regions and DMA
> +  buffers are mapped as shared memory, which means the hypervisor controls
> +  their content. Shared memory must never be used for sensitive data.
> +  See https://docs.kernel.org/arch/x86/tdx.html#ve-on-memory-accesses[#VE on Memory Accesses],
> +  https://docs.kernel.org/arch/x86/tdx.html#shared-memory-conversions[Shared Memory Conversions],
> +  https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel TDX Guest Kernel Security Specification]
> +* S3 (suspend-to-RAM) and hibernation (S4) are not supported on the host
> +  when TDX is enabled.
> +  See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[interaction-vs-s3-and-deeper-states]
> +* Physical https://docs.kernel.org/arch/x86/tdx.html#cpu-hotplug[CPU Hotplug (ACPI)] is not supported when TDX is enabled. Logical
> +  CPU online/offline is supported.
> +* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No SMM support].
> +  TDX does not allow the hypervisor to manipulate guest
> +  register states, which SMM requires.
> +* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No readonly support for private memory].
> +
> +*Example Configuration:*
> +
> +----
> +# qm set <vmid> -intel-tdx 1
> +----

this seems wrong:

--->8---
root@host:~# qm set 787878 -intel-tdx 1
400 Parameter verification failed.
intel-tdx: invalid format - format error
intel-tdx.type: value '1' does not have a value in the enumeration 'tdx'
intel-tdx.attestation: property is missing and it is not optional

qm set <vmid> [OPTIONS]
root@host:~# qm set 787878 -intel-tdx tdx
400 Parameter verification failed.
intel-tdx: invalid format - format error
intel-tdx.attestation: property is missing and it is not optional

qm set <vmid> [OPTIONS]
root@host:~# qm set 787878 -intel-tdx tdx,attestation=0
update VM 787878: -intel-tdx tdx,attestation=0
---8<---

maybe the attestation param was intended to be optional, but '1' is
definitely not in the enum for the 'tdx-type' default key


> +
> +This enables Intel TDX for the specified VM. Proxmox configures QEMU to create
> +a TDX guest by instantiating the `tdx-guest` object and setting the
> +`confidential-guest-support` machine property.
> +See https://www.qemu.org/docs/master/system/i386/tdx.html#launching-a-td-tdx-vm[Launching a TD]
> +
> +The VM must also use a TDVF-enabled firmware image.
> +See https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[trust-domain-virtual-firmware-tdvf]
> +
> +The QEMU TDX guest object supports configurable attributes via a raw 64-bit
> +field. The most relevant bit is DEBUG (bit 0), which enables off-TD debug mode
> +and allows the hypervisor to inspect TD state. Debug mode should only be
> +enabled for development and troubleshooting, as it reduces the security
> +guarantees of the TD. See the
> +https://www.qemu.org/docs/master/system/i386/tdx.html#td-attributes[TD attributes]
> +for details on configurable TDX attributes.
> +
> +*Verify TDX in the VM*
> +
> +The `dmesg` output should look similar to this
> +footnote:[Ubuntu TDX guide https://github.com/canonical/tdx/blob/3.3/README.md#7-verify-td]:
> +
> +----
> +# dmesg | grep -i tdx
> +[...] tdx: Guest detected
> +[...] DMI: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 2023.05-2+tdx1.0~ubuntu23.10.1 10/17/2023
> +[...] process: using TDX aware idle routine
> +[...] Memory Encryption Features active: Intel TDX
> +----
> +
> +Links:
> +
> +* https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html[Intel IDX documentation]
> +* https://www.qemu.org/docs/master/system/i386/tdx.html[QEMU Intel IDX]

it's "TDX" not "IDX" (both times)

> +* https://docs.kernel.org/virt/kvm/x86/intel-tdx.html
> +* https://docs.kernel.org/arch/x86/tdx.html
> +* https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel Trust Domain Extension Linux Guest Kernel Security Specification]
> +* https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[What Intel® Xeon Processors Support for Intel® Trust Domain Extensions (Intel® TDX)?]
> +* https://www.intel.com/content/www/us/en/developer/articles/technical/tdx-performance-analysis-reference-documentation.html[Intel Trust Domain Extensions (Intel® TDX) Performance Analysis Reference Documentation]
> +
>   [[qm_network_device]]
>   Network Device
>   ~~~~~~~~~~~~~~