€•Ý      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ /translations/zh_CN/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ /translations/zh_TW/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ /translations/it_IT/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ /translations/ja_JP/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ /translations/ko_KR/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ /translations/sp_SP/arch/x86/tdx”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒ:/var/lib/git/docbuild/linux/Documentation/arch/x86/tdx.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ#Intel Trust Domain Extensions (TDX)”h]”hŒ#Intel Trust Domain Extensions (TDX)”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hX/  Intel's Trust Domain Extensions (TDX) protect confidential guest VMs from
the host and physical attacks by isolating the guest register state and by
encrypting the guest memory. In TDX, a special module running in a special
mode sits between the host and the guest and manages the guest/host
separation.”h]”hX1  Intelâ€™s Trust Domain Extensions (TDX) protect confidential guest VMs from
the host and physical attacks by isolating the guest register state and by
encrypting the guest memory. In TDX, a special module running in a special
mode sits between the host and the guest and manages the guest/host
separation.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒTDX Host Kernel Support”h]”hŒTDX Host Kernel Support”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÙhžhhŸh³h KubhÊ)”}”(hX%  TDX introduces a new CPU mode called Secure Arbitration Mode (SEAM) and
a new isolated range pointed by the SEAM Ranger Register (SEAMRR).  A
CPU-attested software module called 'the TDX module' runs inside the new
isolated range to provide the functionalities to manage and run protected
VMs.”h]”hX)  TDX introduces a new CPU mode called Secure Arbitration Mode (SEAM) and
a new isolated range pointed by the SEAM Ranger Register (SEAMRR).  A
CPU-attested software module called â€˜the TDX moduleâ€™ runs inside the new
isolated range to provide the functionalities to manage and run protected
VMs.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubhÊ)”}”(hX  TDX also leverages Intel Multi-Key Total Memory Encryption (MKTME) to
provide crypto-protection to the VMs.  TDX reserves part of MKTME KeyIDs
as TDX private KeyIDs, which are only accessible within the SEAM mode.
BIOS is responsible for partitioning legacy MKTME KeyIDs and TDX KeyIDs.”h]”hX  TDX also leverages Intel Multi-Key Total Memory Encryption (MKTME) to
provide crypto-protection to the VMs.  TDX reserves part of MKTME KeyIDs
as TDX private KeyIDs, which are only accessible within the SEAM mode.
BIOS is responsible for partitioning legacy MKTME KeyIDs and TDX KeyIDs.”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubhÊ)”}”(hŒþBefore the TDX module can be used to create and run protected VMs, it
must be loaded into the isolated range and properly initialized.  The TDX
architecture doesn't require the BIOS to load the TDX module, but the
kernel assumes it is loaded by the BIOS.”h]”hX   Before the TDX module can be used to create and run protected VMs, it
must be loaded into the isolated range and properly initialized.  The TDX
architecture doesnâ€™t require the BIOS to load the TDX module, but the
kernel assumes it is loaded by the BIOS.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubhµ)”}”(hhh]”(hº)”}”(hŒTDX boot-time detection”h]”hŒTDX boot-time detection”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K!ubhÊ)”}”(hŒ{The kernel detects TDX by detecting TDX private KeyIDs during kernel
boot.  Below dmesg shows when TDX is enabled by BIOS::”h]”hŒzThe kernel detects TDX by detecting TDX private KeyIDs during kernel
boot.  Below dmesg shows when TDX is enabled by BIOS:”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K#hj  hžhubhŒliteral_block”“”)”}”(hŒ:[..] virt/tdx: BIOS enabled: private KeyID range: [16, 64)”h]”hŒ:[..] virt/tdx: BIOS enabled: private KeyID range: [16, 64)”…””}”hj5  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h K&hj  hžhubeh}”(h]”Œtdx-boot-time-detection”ah ]”h"]”Œtdx boot-time detection”ah$]”h&]”uh1h´hhÙhžhhŸh³h K!ubhµ)”}”(hhh]”(hº)”}”(hŒTDX module initialization”h]”hŒTDX module initialization”…””}”(hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjK  hžhhŸh³h K)ubhÊ)”}”(hŒThe kernel talks to the TDX module via the new SEAMCALL instruction.  The
TDX module implements SEAMCALL leaf functions to allow the kernel to
initialize it.”h]”hŒThe kernel talks to the TDX module via the new SEAMCALL instruction.  The
TDX module implements SEAMCALL leaf functions to allow the kernel to
initialize it.”…””}”(hj\  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K+hjK  hžhubhÊ)”}”(hŒ³If the TDX module isn't loaded, the SEAMCALL instruction fails with a
special error.  In this case the kernel fails the module initialization
and reports the module isn't loaded::”h]”hŒ¶If the TDX module isnâ€™t loaded, the SEAMCALL instruction fails with a
special error.  In this case the kernel fails the module initialization
and reports the module isnâ€™t loaded:”…””}”(hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hjK  hžhubj4  )”}”(hŒ [..] virt/tdx: module not loaded”h]”hŒ [..] virt/tdx: module not loaded”…””}”hjx  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h K3hjK  hžhubhÊ)”}”(hX'  Initializing the TDX module consumes roughly ~1/256th system RAM size to
use it as 'metadata' for the TDX memory.  It also takes additional CPU
time to initialize those metadata along with the TDX module itself.  Both
are not trivial.  The kernel initializes the TDX module at runtime on
demand.”h]”hX+  Initializing the TDX module consumes roughly ~1/256th system RAM size to
use it as â€˜metadataâ€™ for the TDX memory.  It also takes additional CPU
time to initialize those metadata along with the TDX module itself.  Both
are not trivial.  The kernel initializes the TDX module at runtime on
demand.”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K5hjK  hžhubhÊ)”}”(hŒ’Besides initializing the TDX module, a per-cpu initialization SEAMCALL
must be done on one cpu before any other SEAMCALLs can be made on that
cpu.”h]”hŒ’Besides initializing the TDX module, a per-cpu initialization SEAMCALL
must be done on one cpu before any other SEAMCALLs can be made on that
cpu.”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K;hjK  hžhubhÊ)”}”(hŒ The kernel provides two functions, tdx_enable() and tdx_cpu_enable() to
allow the user of TDX to enable the TDX module and enable TDX on local
cpu respectively.”h]”hŒ The kernel provides two functions, tdx_enable() and tdx_cpu_enable() to
allow the user of TDX to enable the TDX module and enable TDX on local
cpu respectively.”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K?hjK  hžhubhÊ)”}”(hŒåMaking SEAMCALL requires VMXON has been done on that CPU.  Currently only
KVM implements VMXON.  For now both tdx_enable() and tdx_cpu_enable()
don't do VMXON internally (not trivial), but depends on the caller to
guarantee that.”h]”hŒçMaking SEAMCALL requires VMXON has been done on that CPU.  Currently only
KVM implements VMXON.  For now both tdx_enable() and tdx_cpu_enable()
donâ€™t do VMXON internally (not trivial), but depends on the caller to
guarantee that.”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KChjK  hžhubhÊ)”}”(hŒ¦To enable TDX, the caller of TDX should: 1) temporarily disable CPU
hotplug; 2) do VMXON and tdx_enable_cpu() on all online cpus; 3) call
tdx_enable().  For example::”h]”hŒ¥To enable TDX, the caller of TDX should: 1) temporarily disable CPU
hotplug; 2) do VMXON and tdx_enable_cpu() on all online cpus; 3) call
tdx_enable().  For example:”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KHhjK  hžhubj4  )”}”(hŒ—cpus_read_lock();
on_each_cpu(vmxon_and_tdx_cpu_enable());
ret = tdx_enable();
cpus_read_unlock();
if (ret)
        goto no_tdx;
// TDX is ready to use”h]”hŒ—cpus_read_lock();
on_each_cpu(vmxon_and_tdx_cpu_enable());
ret = tdx_enable();
cpus_read_unlock();
if (ret)
        goto no_tdx;
// TDX is ready to use”…””}”hjÌ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h KLhjK  hžhubhÊ)”}”(hX  And the caller of TDX must guarantee the tdx_cpu_enable() has been
successfully done on any cpu before it wants to run any other SEAMCALL.
A typical usage is do both VMXON and tdx_cpu_enable() in CPU hotplug
online callback, and refuse to online if tdx_cpu_enable() fails.”h]”hX  And the caller of TDX must guarantee the tdx_cpu_enable() has been
successfully done on any cpu before it wants to run any other SEAMCALL.
A typical usage is do both VMXON and tdx_cpu_enable() in CPU hotplug
online callback, and refuse to online if tdx_cpu_enable() fails.”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KThjK  hžhubhÊ)”}”(hŒJUser can consult dmesg to see whether the TDX module has been initialized.”h]”hŒJUser can consult dmesg to see whether the TDX module has been initialized.”…””}”(hjè  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KYhjK  hžhubhÊ)”}”(hŒQIf the TDX module is initialized successfully, dmesg shows something
like below::”h]”hŒPIf the TDX module is initialized successfully, dmesg shows something
like below:”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K[hjK  hžhubj4  )”}”(hŒN[..] virt/tdx: 262668 KBs allocated for PAMT
[..] virt/tdx: module initialized”h]”hŒN[..] virt/tdx: 262668 KBs allocated for PAMT
[..] virt/tdx: module initialized”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h K^hjK  hžhubhÊ)”}”(hŒRIf the TDX module failed to initialize, dmesg also shows it failed to
initialize::”h]”hŒQIf the TDX module failed to initialize, dmesg also shows it failed to
initialize:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KahjK  hžhubj4  )”}”(hŒ/[..] virt/tdx: module initialization failed ...”h]”hŒ/[..] virt/tdx: module initialization failed ...”…””}”hj   sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h KdhjK  hžhubeh}”(h]”Œtdx-module-initialization”ah ]”h"]”Œtdx module initialization”ah$]”h&]”uh1h´hhÙhžhhŸh³h K)ubhµ)”}”(hhh]”(hº)”}”(hŒ*TDX Interaction to Other Kernel Components”h]”hŒ*TDX Interaction to Other Kernel Components”…””}”(hj9  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj6  hžhhŸh³h Kgubhµ)”}”(hhh]”(hº)”}”(hŒTDX Memory Policy”h]”hŒTDX Memory Policy”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjG  hžhhŸh³h KjubhÊ)”}”(hXG  TDX reports a list of "Convertible Memory Region" (CMR) to tell the
kernel which memory is TDX compatible.  The kernel needs to build a list
of memory regions (out of CMRs) as "TDX-usable" memory and pass those
regions to the TDX module.  Once this is done, those "TDX-usable" memory
regions are fixed during module's lifetime.”h]”hXU  TDX reports a list of â€œConvertible Memory Regionâ€ (CMR) to tell the
kernel which memory is TDX compatible.  The kernel needs to build a list
of memory regions (out of CMRs) as â€œTDX-usableâ€ memory and pass those
regions to the TDX module.  Once this is done, those â€œTDX-usableâ€ memory
regions are fixed during moduleâ€™s lifetime.”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KlhjG  hžhubhÊ)”}”(hX8  To keep things simple, currently the kernel simply guarantees all pages
in the page allocator are TDX memory.  Specifically, the kernel uses all
system memory in the core-mm "at the time of TDX module initialization"
as TDX memory, and in the meantime, refuses to online any non-TDX-memory
in the memory hotplug.”h]”hX<  To keep things simple, currently the kernel simply guarantees all pages
in the page allocator are TDX memory.  Specifically, the kernel uses all
system memory in the core-mm â€œat the time of TDX module initializationâ€
as TDX memory, and in the meantime, refuses to online any non-TDX-memory
in the memory hotplug.”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KrhjG  hžhubeh}”(h]”Œtdx-memory-policy”ah ]”h"]”Œtdx memory policy”ah$]”h&]”uh1h´hj6  hžhhŸh³h Kjubhµ)”}”(hhh]”(hº)”}”(hŒPhysical Memory Hotplug”h]”hŒPhysical Memory Hotplug”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj|  hžhhŸh³h KyubhÊ)”}”(hX  Note TDX assumes convertible memory is always physically present during
machine's runtime.  A non-buggy BIOS should never support hot-removal of
any convertible memory.  This implementation doesn't handle ACPI memory
removal but depends on the BIOS to behave correctly.”h]”hX  Note TDX assumes convertible memory is always physically present during
machineâ€™s runtime.  A non-buggy BIOS should never support hot-removal of
any convertible memory.  This implementation doesnâ€™t handle ACPI memory
removal but depends on the BIOS to behave correctly.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K{hj|  hžhubeh}”(h]”Œphysical-memory-hotplug”ah ]”h"]”Œphysical memory hotplug”ah$]”h&]”uh1h´hj6  hžhhŸh³h Kyubhµ)”}”(hhh]”(hº)”}”(hŒCPU Hotplug”h]”hŒCPU Hotplug”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj£  hžhhŸh³h KubhÊ)”}”(hŒüTDX module requires the per-cpu initialization SEAMCALL must be done on
one cpu before any other SEAMCALLs can be made on that cpu.  The kernel
provides tdx_cpu_enable() to let the user of TDX to do it when the user
wants to use a new cpu for TDX task.”h]”hŒüTDX module requires the per-cpu initialization SEAMCALL must be done on
one cpu before any other SEAMCALLs can be made on that cpu.  The kernel
provides tdx_cpu_enable() to let the user of TDX to do it when the user
wants to use a new cpu for TDX task.”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kƒhj£  hžhubhÊ)”}”(hXN  TDX doesn't support physical (ACPI) CPU hotplug.  During machine boot,
TDX verifies all boot-time present logical CPUs are TDX compatible before
enabling TDX.  A non-buggy BIOS should never support hot-add/removal of
physical CPU.  Currently the kernel doesn't handle physical CPU hotplug,
but depends on the BIOS to behave correctly.”h]”hXR  TDX doesnâ€™t support physical (ACPI) CPU hotplug.  During machine boot,
TDX verifies all boot-time present logical CPUs are TDX compatible before
enabling TDX.  A non-buggy BIOS should never support hot-add/removal of
physical CPU.  Currently the kernel doesnâ€™t handle physical CPU hotplug,
but depends on the BIOS to behave correctly.”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kˆhj£  hžhubhÊ)”}”(hŒxNote TDX works with CPU logical online/offline, thus the kernel still
allows to offline logical CPU and online it again.”h]”hŒxNote TDX works with CPU logical online/offline, thus the kernel still
allows to offline logical CPU and online it again.”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŽhj£  hžhubeh}”(h]”Œcpu-hotplug”ah ]”h"]”Œcpu hotplug”ah$]”h&]”uh1h´hj6  hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒKexec()”h]”hŒKexec()”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjæ  hžhhŸh³h K’ubhÊ)”}”(hŒ TDX host support currently lacks the ability to handle kexec.  For
simplicity only one of them can be enabled in the Kconfig.  This will be
fixed in the future.”h]”hŒ TDX host support currently lacks the ability to handle kexec.  For
simplicity only one of them can be enabled in the Kconfig.  This will be
fixed in the future.”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K”hjæ  hžhubeh}”(h]”Œkexec”ah ]”h"]”Œkexec()”ah$]”h&]”uh1h´hj6  hžhhŸh³h K’ubhµ)”}”(hhh]”(hº)”}”(hŒErratum”h]”hŒErratum”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K™ubhÊ)”}”(hŒÖThe first few generations of TDX hardware have an erratum.  A partial
write to a TDX private memory cacheline will silently "poison" the
line.  Subsequent reads will consume the poison and generate a machine
check.”h]”hŒÚThe first few generations of TDX hardware have an erratum.  A partial
write to a TDX private memory cacheline will silently â€œpoisonâ€ the
line.  Subsequent reads will consume the poison and generate a machine
check.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K›hj  hžhubhÊ)”}”(hX  A partial write is a memory write where a write transaction of less than
cacheline lands at the memory controller.  The CPU does these via
non-temporal write instructions (like MOVNTI), or through UC/WC memory
mappings.  Devices can also do partial writes via DMA.”h]”hX  A partial write is a memory write where a write transaction of less than
cacheline lands at the memory controller.  The CPU does these via
non-temporal write instructions (like MOVNTI), or through UC/WC memory
mappings.  Devices can also do partial writes via DMA.”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K hj  hžhubhÊ)”}”(hX  Theoretically, a kernel bug could do partial write to TDX private memory
and trigger unexpected machine check.  What's more, the machine check
code will present these as "Hardware error" when they were, in fact, a
software-triggered issue.  But in the end, this issue is hard to trigger.”h]”hX%  Theoretically, a kernel bug could do partial write to TDX private memory
and trigger unexpected machine check.  Whatâ€™s more, the machine check
code will present these as â€œHardware errorâ€ when they were, in fact, a
software-triggered issue.  But in the end, this issue is hard to trigger.”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¥hj  hžhubhÊ)”}”(hŒ±If the platform has such erratum, the kernel prints additional message in
machine check handler to tell user the machine check may be caused by
kernel bug on TDX private memory.”h]”hŒ±If the platform has such erratum, the kernel prints additional message in
machine check handler to tell user the machine check may be caused by
kernel bug on TDX private memory.”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kªhj  hžhubeh}”(h]”Œerratum”ah ]”h"]”Œerratum”ah$]”h&]”uh1h´hj6  hžhhŸh³h K™ubhµ)”}”(hhh]”(hº)”}”(hŒ#Interaction vs S3 and deeper states”h]”hŒ#Interaction vs S3 and deeper states”…””}”(hja  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj^  hžhhŸh³h K¯ubhÊ)”}”(hŒÂTDX cannot survive from S3 and deeper states.  The hardware resets and
disables TDX completely when platform goes to S3 and deeper.  Both TDX
guests and the TDX module get destroyed permanently.”h]”hŒÂTDX cannot survive from S3 and deeper states.  The hardware resets and
disables TDX completely when platform goes to S3 and deeper.  Both TDX
guests and the TDX module get destroyed permanently.”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K±hj^  hžhubhÊ)”}”(hŒ»The kernel uses S3 for suspend-to-ram, and use S4 and deeper states for
hibernation.  Currently, for simplicity, the kernel chooses to make TDX
mutually exclusive with S3 and hibernation.”h]”hŒ»The kernel uses S3 for suspend-to-ram, and use S4 and deeper states for
hibernation.  Currently, for simplicity, the kernel chooses to make TDX
mutually exclusive with S3 and hibernation.”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kµhj^  hžhubhÊ)”}”(hŒQThe kernel disables TDX during early boot when hibernation support is
available::”h]”hŒPThe kernel disables TDX during early boot when hibernation support is
available:”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¹hj^  hžhubj4  )”}”(hŒD[..] virt/tdx: initialization failed: Hibernation support is enabled”h]”hŒD[..] virt/tdx: initialization failed: Hibernation support is enabled”…””}”hj™  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j3  hŸh³h K¼hj^  hžhubhÊ)”}”(hŒQAdd 'nohibernate' kernel command line to disable hibernation in order to
use TDX.”h]”hŒUAdd â€˜nohibernateâ€™ kernel command line to disable hibernation in order to
use TDX.”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¾hj^  hžhubhÊ)”}”(hŒACPI S3 is disabled during kernel early boot if TDX is enabled.  The user
needs to turn off TDX in the BIOS in order to use S3.”h]”hŒACPI S3 is disabled during kernel early boot if TDX is enabled.  The user
needs to turn off TDX in the BIOS in order to use S3.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÁhj^  hžhubeh}”(h]”Œ#interaction-vs-s3-and-deeper-states”ah ]”h"]”Œ#interaction vs s3 and deeper states”ah$]”h&]”uh1h´hj6  hžhhŸh³h K¯ubeh}”(h]”Œ*tdx-interaction-to-other-kernel-components”ah ]”h"]”Œ*tdx interaction to other kernel components”ah$]”h&]”uh1h´hhÙhžhhŸh³h Kgubeh}”(h]”Œtdx-host-kernel-support”ah ]”h"]”Œtdx host kernel support”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒTDX Guest Support”h]”hŒTDX Guest Support”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÛ  hžhhŸh³h KÅubhÊ)”}”(hXL  Since the host cannot directly access guest registers or memory, much
normal functionality of a hypervisor must be moved into the guest. This is
implemented using a Virtualization Exception (#VE) that is handled by the
guest kernel. A #VE is handled entirely inside the guest kernel, but some
require the hypervisor to be consulted.”h]”hXL  Since the host cannot directly access guest registers or memory, much
normal functionality of a hypervisor must be moved into the guest. This is
implemented using a Virtualization Exception (#VE) that is handled by the
guest kernel. A #VE is handled entirely inside the guest kernel, but some
require the hypervisor to be consulted.”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÆhjÛ  hžhubhÊ)”}”(hŒpTDX includes new hypercall-like mechanisms for communicating from the
guest to the hypervisor or the TDX module.”h]”hŒpTDX includes new hypercall-like mechanisms for communicating from the
guest to the hypervisor or the TDX module.”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÌhjÛ  hžhubhµ)”}”(hhh]”(hº)”}”(hŒNew TDX Exceptions”h]”hŒNew TDX Exceptions”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KÐubhÊ)”}”(hŒªTDX guests behave differently from bare-metal and traditional VMX guests.
In TDX guests, otherwise normal instructions or memory accesses can cause
#VE or #GP exceptions.”h]”hŒªTDX guests behave differently from bare-metal and traditional VMX guests.
In TDX guests, otherwise normal instructions or memory accesses can cause
#VE or #GP exceptions.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÒhj  hžhubhÊ)”}”(hŒxInstructions marked with an '*' conditionally cause exceptions.  The
details for these instructions are discussed below.”h]”hŒ|Instructions marked with an â€˜*â€™ conditionally cause exceptions.  The
details for these instructions are discussed below.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÖhj  hžhubhµ)”}”(hhh]”(hº)”}”(hŒInstruction-based #VE”h]”hŒInstruction-based #VE”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj5  hžhhŸh³h KÚubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒPort I/O (INS, OUTS, IN, OUT)”h]”hÊ)”}”(hjO  h]”hŒPort I/O (INS, OUTS, IN, OUT)”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÜhjM  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒHLT”h]”hÊ)”}”(hjf  h]”hŒHLT”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÝhjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒMONITOR, MWAIT”h]”hÊ)”}”(hj}  h]”hŒMONITOR, MWAIT”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÞhj{  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒWBINVD, INVD”h]”hÊ)”}”(hj”  h]”hŒWBINVD, INVD”…””}”(hj–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kßhj’  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒVMCALL”h]”hÊ)”}”(hj«  h]”hŒVMCALL”…””}”(hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kàhj©  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒRDMSR*,WRMSR*”h]”hÊ)”}”(hjÂ  h]”hŒRDMSR*,WRMSR*”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KáhjÀ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h NubjL  )”}”(hŒCPUID*
”h]”hÊ)”}”(hŒCPUID*”h]”hŒCPUID*”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kâhj×  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjH  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jF  hŸh³h KÜhj5  hžhubeh}”(h]”Œinstruction-based-ve”ah ]”h"]”Œinstruction-based #ve”ah$]”h&]”uh1h´hj  hžhhŸh³h KÚubhµ)”}”(hhh]”(hº)”}”(hŒInstruction-based #GP”h]”hŒInstruction-based #GP”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÿ  hžhhŸh³h KåubjG  )”}”(hhh]”(jL  )”}”(hŒ|All VMX instructions: INVEPT, INVVPID, VMCLEAR, VMFUNC, VMLAUNCH,
VMPTRLD, VMPTRST, VMREAD, VMRESUME, VMWRITE, VMXOFF, VMXON”h]”hÊ)”}”(hŒ|All VMX instructions: INVEPT, INVVPID, VMCLEAR, VMFUNC, VMLAUNCH,
VMPTRLD, VMPTRST, VMREAD, VMRESUME, VMWRITE, VMXOFF, VMXON”h]”hŒ|All VMX instructions: INVEPT, INVVPID, VMCLEAR, VMFUNC, VMLAUNCH,
VMPTRLD, VMPTRST, VMREAD, VMRESUME, VMWRITE, VMXOFF, VMXON”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kçhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h NubjL  )”}”(hŒENCLS, ENCLU”h]”hÊ)”}”(hj-  h]”hŒENCLS, ENCLU”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kéhj+  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h NubjL  )”}”(hŒGETSEC”h]”hÊ)”}”(hjD  h]”hŒGETSEC”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KêhjB  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h NubjL  )”}”(hŒRSM”h]”hÊ)”}”(hj[  h]”hŒRSM”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KëhjY  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h NubjL  )”}”(hŒENQCMD”h]”hÊ)”}”(hjr  h]”hŒENQCMD”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kìhjp  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h NubjL  )”}”(hŒRDMSR*,WRMSR*
”h]”hÊ)”}”(hŒRDMSR*,WRMSR*”h]”hŒRDMSR*,WRMSR*”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kíhj‡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hj  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jõ  jö  uh1jF  hŸh³h Kçhjÿ  hžhubeh}”(h]”Œinstruction-based-gp”ah ]”h"]”Œinstruction-based #gp”ah$]”h&]”uh1h´hj  hžhhŸh³h Kåubhµ)”}”(hhh]”(hº)”}”(hŒRDMSR/WRMSR Behavior”h]”hŒRDMSR/WRMSR Behavior”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj­  hžhhŸh³h KðubhÊ)”}”(hŒ0MSR access behavior falls into three categories:”h]”hŒ0MSR access behavior falls into three categories:”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kòhj­  hžhubjG  )”}”(hhh]”(jL  )”}”(hŒ#GP generated”h]”hÊ)”}”(hjÑ  h]”hŒ#GP generated”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KôhjÏ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjÌ  hžhhŸh³h NubjL  )”}”(hŒ#VE generated”h]”hÊ)”}”(hjè  h]”hŒ#VE generated”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kõhjæ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjÌ  hžhhŸh³h NubjL  )”}”(hŒ"Just works"
”h]”hÊ)”}”(hŒ"Just works"”h]”hŒâ€œJust worksâ€”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Köhjý  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjÌ  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jõ  jö  uh1jF  hŸh³h Kôhj­  hžhubhÊ)”}”(hŒ»In general, the #GP MSRs should not be used in guests.  Their use likely
indicates a bug in the guest.  The guest may try to handle the #GP with a
hypercall but it is unlikely to succeed.”h]”hŒ»In general, the #GP MSRs should not be used in guests.  Their use likely
indicates a bug in the guest.  The guest may try to handle the #GP with a
hypercall but it is unlikely to succeed.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Køhj­  hžhubhÊ)”}”(hŒ‚The #VE MSRs are typically able to be handled by the hypervisor.  Guests
can make a hypercall to the hypervisor to handle the #VE.”h]”hŒ‚The #VE MSRs are typically able to be handled by the hypervisor.  Guests
can make a hypercall to the hypervisor to handle the #VE.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kühj­  hžhubhÊ)”}”(hX  The "just works" MSRs do not need any special guest handling.  They might
be implemented by directly passing through the MSR to the hardware or by
trapping and handling in the TDX module.  Other than possibly being slow,
these MSRs appear to function just as they would on bare metal.”h]”hX   The â€œjust worksâ€ MSRs do not need any special guest handling.  They might
be implemented by directly passing through the MSR to the hardware or by
trapping and handling in the TDX module.  Other than possibly being slow,
these MSRs appear to function just as they would on bare metal.”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kÿhj­  hžhubeh}”(h]”Œrdmsr-wrmsr-behavior”ah ]”h"]”Œrdmsr/wrmsr behavior”ah$]”h&]”uh1h´hj  hžhhŸh³h Kðubhµ)”}”(hhh]”(hº)”}”(hŒCPUID Behavior”h]”hŒCPUID Behavior”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjM  hžhhŸh³h MubhÊ)”}”(hŒêFor some CPUID leaves and sub-leaves, the virtualized bit fields of CPUID
return values (in guest EAX/EBX/ECX/EDX) are configurable by the
hypervisor. For such cases, the Intel TDX module architecture defines two
virtualization types:”h]”hŒêFor some CPUID leaves and sub-leaves, the virtualized bit fields of CPUID
return values (in guest EAX/EBX/ECX/EDX) are configurable by the
hypervisor. For such cases, the Intel TDX module architecture defines two
virtualization types:”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MhjM  hžhubjG  )”}”(hhh]”(jL  )”}”(hŒMBit fields for which the hypervisor controls the value seen by the guest
TD.
”h]”hÊ)”}”(hŒLBit fields for which the hypervisor controls the value seen by the guest
TD.”h]”hŒLBit fields for which the hypervisor controls the value seen by the guest
TD.”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhjo  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjl  hžhhŸh³h NubjL  )”}”(hŒçBit fields for which the hypervisor configures the value such that the
guest TD either sees their native value or a value of 0.  For these bit
fields, the hypervisor can mask off the native values, but it can not
turn *on* values.
”h]”hÊ)”}”(hŒæBit fields for which the hypervisor configures the value such that the
guest TD either sees their native value or a value of 0.  For these bit
fields, the hypervisor can mask off the native values, but it can not
turn *on* values.”h]”(hŒÚBit fields for which the hypervisor configures the value such that the
guest TD either sees their native value or a value of 0.  For these bit
fields, the hypervisor can mask off the native values, but it can not
turn ”…””}”(hj‹  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*on*”h]”hŒon”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j“  hj‹  ubhŒ values.”…””}”(hj‹  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj‡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjl  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jõ  jö  uh1jF  hŸh³h MhjM  hžhubhÊ)”}”(hŒ«A #VE is generated for CPUID leaves and sub-leaves that the TDX module does
not know how to handle. The guest kernel may ask the hypervisor for the
value with a hypercall.”h]”hŒ«A #VE is generated for CPUID leaves and sub-leaves that the TDX module does
not know how to handle. The guest kernel may ask the hypervisor for the
value with a hypercall.”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MhjM  hžhubeh}”(h]”Œcpuid-behavior”ah ]”h"]”Œcpuid behavior”ah$]”h&]”uh1h´hj  hžhhŸh³h Mubeh}”(h]”Œnew-tdx-exceptions”ah ]”h"]”Œnew tdx exceptions”ah$]”h&]”uh1h´hjÛ  hžhhŸh³h KÐubhµ)”}”(hhh]”(hº)”}”(hŒ#VE on Memory Accesses”h]”hŒ#VE on Memory Accesses”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj×  hžhhŸh³h MubhÊ)”}”(hX   There are essentially two classes of TDX memory: private and shared.
Private memory receives full TDX protections.  Its content is protected
against access from the hypervisor.  Shared memory is expected to be
shared between guest and hypervisor and does not receive full TDX
protections.”h]”hX   There are essentially two classes of TDX memory: private and shared.
Private memory receives full TDX protections.  Its content is protected
against access from the hypervisor.  Shared memory is expected to be
shared between guest and hypervisor and does not receive full TDX
protections.”…””}”(hjè  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj×  hžhubhÊ)”}”(hX  A TD guest is in control of whether its memory accesses are treated as
private or shared.  It selects the behavior with a bit in its page table
entries.  This helps ensure that a guest does not place sensitive
information in shared memory, exposing it to the untrusted hypervisor.”h]”hX  A TD guest is in control of whether its memory accesses are treated as
private or shared.  It selects the behavior with a bit in its page table
entries.  This helps ensure that a guest does not place sensitive
information in shared memory, exposing it to the untrusted hypervisor.”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M!hj×  hžhubhµ)”}”(hhh]”(hº)”}”(hŒ#VE on Shared Memory”h]”hŒ#VE on Shared Memory”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h M'ubhÊ)”}”(hXi  Access to shared mappings can cause a #VE.  The hypervisor ultimately
controls whether a shared memory access causes a #VE, so the guest must be
careful to only reference shared pages it can safely handle a #VE.  For
instance, the guest should be careful not to access shared memory in the
#VE handler before it reads the #VE info structure (TDG.VP.VEINFO.GET).”h]”hXi  Access to shared mappings can cause a #VE.  The hypervisor ultimately
controls whether a shared memory access causes a #VE, so the guest must be
careful to only reference shared pages it can safely handle a #VE.  For
instance, the guest should be careful not to access shared memory in the
#VE handler before it reads the #VE info structure (TDG.VP.VEINFO.GET).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M)hj  hžhubhÊ)”}”(hX“  Shared mapping content is entirely controlled by the hypervisor. The guest
should only use shared mappings for communicating with the hypervisor.
Shared mappings must never be used for sensitive memory content like kernel
stacks.  A good rule of thumb is that hypervisor-shared memory should be
treated the same as memory mapped to userspace.  Both the hypervisor and
userspace are completely untrusted.”h]”hX“  Shared mapping content is entirely controlled by the hypervisor. The guest
should only use shared mappings for communicating with the hypervisor.
Shared mappings must never be used for sensitive memory content like kernel
stacks.  A good rule of thumb is that hypervisor-shared memory should be
treated the same as memory mapped to userspace.  Both the hypervisor and
userspace are completely untrusted.”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M/hj  hžhubhÊ)”}”(hŒ¢MMIO for virtual devices is implemented as shared memory.  The guest must
be careful not to access device MMIO regions unless it is also prepared to
handle a #VE.”h]”hŒ¢MMIO for virtual devices is implemented as shared memory.  The guest must
be careful not to access device MMIO regions unless it is also prepared to
handle a #VE.”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M6hj  hžhubeh}”(h]”Œve-on-shared-memory”ah ]”h"]”Œ#ve on shared memory”ah$]”h&]”uh1h´hj×  hžhhŸh³h M'ubhµ)”}”(hhh]”(hº)”}”(hŒ#VE on Private Pages”h]”hŒ#VE on Private Pages”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjG  hžhhŸh³h M;ubhÊ)”}”(hX8  An access to private mappings can also cause a #VE.  Since all kernel
memory is also private memory, the kernel might theoretically need to
handle a #VE on arbitrary kernel memory accesses.  This is not feasible, so
TDX guests ensure that all guest memory has been "accepted" before memory
is used by the kernel.”h]”hX<  An access to private mappings can also cause a #VE.  Since all kernel
memory is also private memory, the kernel might theoretically need to
handle a #VE on arbitrary kernel memory accesses.  This is not feasible, so
TDX guests ensure that all guest memory has been â€œacceptedâ€ before memory
is used by the kernel.”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M=hjG  hžhubhÊ)”}”(hŒªA modest amount of memory (typically 512M) is pre-accepted by the firmware
before the kernel runs to ensure that the kernel can start up without
being subjected to a #VE.”h]”hŒªA modest amount of memory (typically 512M) is pre-accepted by the firmware
before the kernel runs to ensure that the kernel can start up without
being subjected to a #VE.”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MChjG  hžhubhÊ)”}”(hŒóThe hypervisor is permitted to unilaterally move accepted pages to a
"blocked" state. However, if it does this, page access will not generate a
#VE.  It will, instead, cause a "TD Exit" where the hypervisor is required
to handle the exception.”h]”hŒûThe hypervisor is permitted to unilaterally move accepted pages to a
â€œblockedâ€ state. However, if it does this, page access will not generate a
#VE.  It will, instead, cause a â€œTD Exitâ€ where the hypervisor is required
to handle the exception.”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MGhjG  hžhubeh}”(h]”Œve-on-private-pages”ah ]”h"]”Œ#ve on private pages”ah$]”h&]”uh1h´hj×  hžhhŸh³h M;ubeh}”(h]”Œve-on-memory-accesses”ah ]”h"]”Œ#ve on memory accesses”ah$]”h&]”uh1h´hjÛ  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒLinux #VE handler”h]”hŒLinux #VE handler”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj’  hžhhŸh³h MMubhÊ)”}”(hŒºJust like page faults or #GP's, #VE exceptions can be either handled or be
fatal.  Typically, an unhandled userspace #VE results in a SIGSEGV.
An unhandled kernel #VE results in an oops.”h]”hŒ¼Just like page faults or #GPâ€™s, #VE exceptions can be either handled or be
fatal.  Typically, an unhandled userspace #VE results in a SIGSEGV.
An unhandled kernel #VE results in an oops.”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MOhj’  hžhubhÊ)”}”(hŒÿHandling nested exceptions on x86 is typically nasty business.  A #VE
could be interrupted by an NMI which triggers another #VE and hilarity
ensues.  The TDX #VE architecture anticipated this scenario and includes a
feature to make it slightly less nasty.”h]”hŒÿHandling nested exceptions on x86 is typically nasty business.  A #VE
could be interrupted by an NMI which triggers another #VE and hilarity
ensues.  The TDX #VE architecture anticipated this scenario and includes a
feature to make it slightly less nasty.”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MShj’  hžhubhÊ)”}”(hŒüDuring #VE handling, the TDX module ensures that all interrupts (including
NMIs) are blocked.  The block remains in place until the guest makes a
TDG.VP.VEINFO.GET TDCALL.  This allows the guest to control when interrupts
or a new #VE can be delivered.”h]”hŒüDuring #VE handling, the TDX module ensures that all interrupts (including
NMIs) are blocked.  The block remains in place until the guest makes a
TDG.VP.VEINFO.GET TDCALL.  This allows the guest to control when interrupts
or a new #VE can be delivered.”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MXhj’  hžhubhÊ)”}”(hŒìHowever, the guest kernel must still be careful to avoid potential
#VE-triggering actions (discussed above) while this block is in place.
While the block is in place, any #VE is elevated to a double fault (#DF)
which is not recoverable.”h]”hŒìHowever, the guest kernel must still be careful to avoid potential
#VE-triggering actions (discussed above) while this block is in place.
While the block is in place, any #VE is elevated to a double fault (#DF)
which is not recoverable.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M]hj’  hžhubeh}”(h]”Œlinux-ve-handler”ah ]”h"]”Œlinux #ve handler”ah$]”h&]”uh1h´hjÛ  hžhhŸh³h MMubhµ)”}”(hhh]”(hº)”}”(hŒMMIO handling”h]”hŒMMIO handling”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjã  hžhhŸh³h McubhÊ)”}”(hXR  In non-TDX VMs, MMIO is usually implemented by giving a guest access to a
mapping which will cause a VMEXIT on access, and then the hypervisor
emulates the access.  That is not possible in TDX guests because VMEXIT
will expose the register state to the host. TDX guests don't trust the host
and can't have their state exposed to the host.”h]”hXV  In non-TDX VMs, MMIO is usually implemented by giving a guest access to a
mapping which will cause a VMEXIT on access, and then the hypervisor
emulates the access.  That is not possible in TDX guests because VMEXIT
will expose the register state to the host. TDX guests donâ€™t trust the host
and canâ€™t have their state exposed to the host.”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mehjã  hžhubhÊ)”}”(hŒóIn TDX, MMIO regions typically trigger a #VE exception in the guest.  The
guest #VE handler then emulates the MMIO instruction inside the guest and
converts it into a controlled TDCALL to the host, rather than exposing
guest state to the host.”h]”hŒóIn TDX, MMIO regions typically trigger a #VE exception in the guest.  The
guest #VE handler then emulates the MMIO instruction inside the guest and
converts it into a controlled TDCALL to the host, rather than exposing
guest state to the host.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mkhjã  hžhubhÊ)”}”(hX  MMIO addresses on x86 are just special physical addresses. They can
theoretically be accessed with any instruction that accesses memory.
However, the kernel instruction decoding method is limited. It is only
designed to decode instructions like those generated by io.h macros.”h]”hX  MMIO addresses on x86 are just special physical addresses. They can
theoretically be accessed with any instruction that accesses memory.
However, the kernel instruction decoding method is limited. It is only
designed to decode instructions like those generated by io.h macros.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mphjã  hžhubhÊ)”}”(hŒLMMIO access via other means (like structure overlays) may result in an
oops.”h]”hŒLMMIO access via other means (like structure overlays) may result in an
oops.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Muhjã  hžhubeh}”(h]”Œmmio-handling”ah ]”h"]”Œmmio handling”ah$]”h&]”uh1h´hjÛ  hžhhŸh³h Mcubhµ)”}”(hhh]”(hº)”}”(hŒShared Memory Conversions”h]”hŒShared Memory Conversions”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj4  hžhhŸh³h MyubhÊ)”}”(hXW  All TDX guest memory starts out as private at boot.  This memory can not
be accessed by the hypervisor.  However, some kernel users like device
drivers might have a need to share data with the hypervisor.  To do this,
memory must be converted between shared and private.  This can be
accomplished using some existing memory encryption helpers:”h]”hXW  All TDX guest memory starts out as private at boot.  This memory can not
be accessed by the hypervisor.  However, some kernel users like device
drivers might have a need to share data with the hypervisor.  To do this,
memory must be converted between shared and private.  This can be
accomplished using some existing memory encryption helpers:”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M{hj4  hžhubhŒblock_quote”“”)”}”(hŒx* set_memory_decrypted() converts a range of pages to shared.
* set_memory_encrypted() converts memory back to private.
”h]”jG  )”}”(hhh]”(jL  )”}”(hŒ;set_memory_decrypted() converts a range of pages to shared.”h]”hÊ)”}”(hj^  h]”hŒ;set_memory_decrypted() converts a range of pages to shared.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj\  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjY  ubjL  )”}”(hŒ8set_memory_encrypted() converts memory back to private.
”h]”hÊ)”}”(hŒ7set_memory_encrypted() converts memory back to private.”h]”hŒ7set_memory_encrypted() converts memory back to private.”…””}”(hjw  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M‚hjs  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jK  hjY  ubeh}”(h]”h ]”h"]”h$]”h&]”jõ  Œ*”uh1jF  hŸh³h MhjU  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hŸh³h Mhj4  hžhubhÊ)”}”(hŒœDevice drivers are the primary user of shared memory, but there's no need
to touch every driver. DMA buffers and ioremap() do the conversions
automatically.”h]”hŒžDevice drivers are the primary user of shared memory, but thereâ€™s no need
to touch every driver. DMA buffers and ioremap() do the conversions
automatically.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M„hj4  hžhubhÊ)”}”(hŒ]TDX uses SWIOTLB for most DMA allocations. The SWIOTLB buffer is
converted to shared on boot.”h]”hŒ]TDX uses SWIOTLB for most DMA allocations. The SWIOTLB buffer is
converted to shared on boot.”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mˆhj4  hžhubhÊ)”}”(hŒxFor coherent DMA allocation, the DMA buffer gets converted on the
allocation. Check force_dma_unencrypted() for details.”h]”hŒxFor coherent DMA allocation, the DMA buffer gets converted on the
allocation. Check force_dma_unencrypted() for details.”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M‹hj4  hžhubeh}”(h]”Œshared-memory-conversions”ah ]”h"]”Œshared memory conversions”ah$]”h&]”uh1h´hjÛ  hžhhŸh³h Myubeh}”(h]”Œtdx-guest-support”ah ]”h"]”Œtdx guest support”ah$]”h&]”uh1h´hh¶hžhhŸh³h KÅubhµ)”}”(hhh]”(hº)”}”(hŒAttestation”h]”hŒAttestation”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÒ  hžhhŸh³h MubhÊ)”}”(hX2  Attestation is used to verify the TDX guest trustworthiness to other
entities before provisioning secrets to the guest. For example, a key
server may want to use attestation to verify that the guest is the
desired one before releasing the encryption keys to mount the encrypted
rootfs or a secondary drive.”h]”hX2  Attestation is used to verify the TDX guest trustworthiness to other
entities before provisioning secrets to the guest. For example, a key
server may want to use attestation to verify that the guest is the
desired one before releasing the encryption keys to mount the encrypted
rootfs or a secondary drive.”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M‘hjÒ  hžhubhÊ)”}”(hXŽ  The TDX module records the state of the TDX guest in various stages of
the guest boot process using the build time measurement register (MRTD)
and runtime measurement registers (RTMR). Measurements related to the
guest initial configuration and firmware image are recorded in the MRTD
register. Measurements related to initial state, kernel image, firmware
image, command line options, initrd, ACPI tables, etc are recorded in
RTMR registers. For more details, as an example, please refer to TDX
Virtual Firmware design specification, section titled "TD Measurement".
At TDX guest runtime, the attestation process is used to attest to these
measurements.”h]”hX’  The TDX module records the state of the TDX guest in various stages of
the guest boot process using the build time measurement register (MRTD)
and runtime measurement registers (RTMR). Measurements related to the
guest initial configuration and firmware image are recorded in the MRTD
register. Measurements related to initial state, kernel image, firmware
image, command line options, initrd, ACPI tables, etc are recorded in
RTMR registers. For more details, as an example, please refer to TDX
Virtual Firmware design specification, section titled â€œTD Measurementâ€.
At TDX guest runtime, the attestation process is used to attest to these
measurements.”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M—hjÒ  hžhubhÊ)”}”(hŒXThe attestation process consists of two steps: TDREPORT generation and
Quote generation.”h]”hŒXThe attestation process consists of two steps: TDREPORT generation and
Quote generation.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¢hjÒ  hžhubhÊ)”}”(hXu  TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
from the TDX module. TDREPORT is a fixed-size data structure generated by
the TDX module which contains guest-specific information (such as build
and boot measurements), platform security version, and the MAC to protect
the integrity of the TDREPORT. A user-provided 64-Byte REPORTDATA is used
as input and included in the TDREPORT. Typically it can be some nonce
provided by attestation service so the TDREPORT can be verified uniquely.
More details about the TDREPORT can be found in Intel TDX Module
specification, section titled "TDG.MR.REPORT Leaf".”h]”hXy  TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
from the TDX module. TDREPORT is a fixed-size data structure generated by
the TDX module which contains guest-specific information (such as build
and boot measurements), platform security version, and the MAC to protect
the integrity of the TDREPORT. A user-provided 64-Byte REPORTDATA is used
as input and included in the TDREPORT. Typically it can be some nonce
provided by attestation service so the TDREPORT can be verified uniquely.
More details about the TDREPORT can be found in Intel TDX Module
specification, section titled â€œTDG.MR.REPORT Leafâ€.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¥hjÒ  hžhubhÊ)”}”(hXc  After getting the TDREPORT, the second step of the attestation process
is to send it to the Quoting Enclave (QE) to generate the Quote. TDREPORT
by design can only be verified on the local platform as the MAC key is
bound to the platform. To support remote verification of the TDREPORT,
TDX leverages Intel SGX Quoting Enclave to verify the TDREPORT locally
and convert it to a remotely verifiable Quote. Method of sending TDREPORT
to QE is implementation specific. Attestation software can choose
whatever communication channel available (i.e. vsock or TCP/IP) to
send the TDREPORT to QE and receive the Quote.”h]”hXc  After getting the TDREPORT, the second step of the attestation process
is to send it to the Quoting Enclave (QE) to generate the Quote. TDREPORT
by design can only be verified on the local platform as the MAC key is
bound to the platform. To support remote verification of the TDREPORT,
TDX leverages Intel SGX Quoting Enclave to verify the TDREPORT locally
and convert it to a remotely verifiable Quote. Method of sending TDREPORT
to QE is implementation specific. Attestation software can choose
whatever communication channel available (i.e. vsock or TCP/IP) to
send the TDREPORT to QE and receive the Quote.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¯hjÒ  hžhubeh}”(h]”Œattestation”ah ]”h"]”Œattestation”ah$]”h&]”uh1h´hh¶hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒ
References”h]”hŒ
References”…””}”(hj4	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj1	  hžhhŸh³h MºubhÊ)”}”(hŒ)TDX reference material is collected here:”h]”hŒ)TDX reference material is collected here:”…””}”(hjB	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¼hj1	  hžhubhÊ)”}”(hŒghttps://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html”h]”hŒ	reference”“”)”}”(hjR	  h]”hŒghttps://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html”…””}”(hjV	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jR	  uh1jT	  hjP	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¾hj1	  hžhubeh}”(h]”Œ
references”ah ]”h"]”Œ
references”ah$]”h&]”uh1h´hh¶hžhhŸh³h Mºubeh}”(h]”Œ!intel-trust-domain-extensions-tdx”ah ]”h"]”Œ#intel trust domain extensions (tdx)”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j	  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jw	  jt	  jØ  jÕ  jH  jE  j3  j0  jÐ  jÍ  jy  jv  j   j  jã  jà  j
  j  j[  jX  jÈ  jÅ  jÏ  jÌ  jÔ  jÑ  jü  jù  jª  j§  jJ  jG  jÌ  jÉ  j  jŒ  jD  jA  j‡  j„  jà  jÝ  j1  j.  jÇ  jÄ  j.	  j+	  jo	  jl	  uŒ	nametypes”}”(jw	  ‰jØ  ‰jH  ‰j3  ‰jÐ  ‰jy  ‰j   ‰jã  ‰j
  ‰j[  ‰jÈ  ‰jÏ  ‰jÔ  ‰jü  ‰jª  ‰jJ  ‰jÌ  ‰j  ‰jD  ‰j‡  ‰jà  ‰j1  ‰jÇ  ‰j.	  ‰jo	  ‰uh}”(jt	  h¶jÕ  hÙjE  j  j0  jK  jÍ  j6  jv  jG  j  j|  jà  j£  j  jæ  jX  j  jÅ  j^  jÌ  jÛ  jÑ  j  jù  j5  j§  jÿ  jG  j­  jÉ  jM  jŒ  j×  jA  j  j„  jG  jÝ  j’  j.  jã  jÄ  j4  j+	  jÒ  jl	  j1	  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.