arch/x86/tdx.rst

1 .. SPDX-License-Identifier: GPL-2.0
9 encrypting the guest memory. In TDX, a special module running in a special
18 CPU-attested software module called 'the TDX module' runs inside the new
22 TDX also leverages Intel Multi-Key Total Memory Encryption (MKTME) to
23 provide crypto-protection to the VMs.  TDX reserves part of MKTME KeyIDs
32 TDX boot-time detection
33 -----------------------
41 ---------------------------------------
54 use it as 'metadata' for the TDX memory.  It also takes additional CPU
59 Besides initializing the TDX module, a per-cpu initialization SEAMCALL
103 ------------------------------------------
105 TDX Memory Policy
108 TDX reports a list of "Convertible Memory Region" (CMR) to tell the
109 kernel which memory is TDX compatible.  The kernel needs to build a list
110 of memory regions (out of CMRs) as "TDX-usable" memory and pass those
111 regions to the TDX module.  Once this is done, those "TDX-usable" memory
115 in the page allocator are TDX memory.  Specifically, the kernel uses all
116 system memory in the core-mm "at the time of TDX module initialization"
117 as TDX memory, and in the meantime, refuses to online any non-TDX-memory
118 in the memory hotplug.
120 Physical Memory Hotplug
123 Note TDX assumes convertible memory is always physically present during
124 machine's runtime.  A non-buggy BIOS should never support hot-removal of
125 any convertible memory.  This implementation doesn't handle ACPI memory
131 TDX module requires the per-cpu initialization SEAMCALL must be done on
137 TDX verifies all boot-time present logical CPUs are TDX compatible before
138 enabling TDX.  A non-buggy BIOS should never support hot-add/removal of
156 write to a TDX private memory cacheline will silently "poison" the
160 A partial write is a memory write where a write transaction of less than
161 cacheline lands at the memory controller.  The CPU does these via
162 non-temporal write instructions (like MOVNTI), or through UC/WC memory
165 Theoretically, a kernel bug could do partial write to TDX private memory
168 software-triggered issue.  But in the end, this issue is hard to trigger.
172 kernel bug on TDX private memory.
181 The kernel uses S3 for suspend-to-ram, and use S4 and deeper states for
198 Since the host cannot directly access guest registers or memory, much
204 TDX includes new hypercall-like mechanisms for communicating from the
208 ------------------
210 TDX guests behave differently from bare-metal and traditional VMX guests.
211 In TDX guests, otherwise normal instructions or memory accesses can cause
217 Instruction-based #VE
220 - Port I/O (INS, OUTS, IN, OUT)
221 - HLT
222 - MONITOR, MWAIT
223 - WBINVD, INVD
224 - VMCALL
225 - RDMSR*,WRMSR*
226 - CPUID*
228 Instruction-based #GP
231 - All VMX instructions: INVEPT, INVVPID, VMCLEAR, VMFUNC, VMLAUNCH,
233 - ENCLS, ENCLU
234 - GETSEC
235 - RSM
236 - ENQCMD
237 - RDMSR*,WRMSR*
244 - #GP generated
245 - #VE generated
246 - "Just works"
263 For some CPUID leaves and sub-leaves, the virtualized bit fields of CPUID
268 - Bit fields for which the hypervisor controls the value seen by the guest
271 - Bit fields for which the hypervisor configures the value such that the
276 A #VE is generated for CPUID leaves and sub-leaves that the TDX module does
280 #VE on Memory Accesses
281 ----------------------
283 There are essentially two classes of TDX memory: private and shared.
284 Private memory receives full TDX protections.  Its content is protected
285 against access from the hypervisor.  Shared memory is expected to be
286 shared between guest and hypervisor and does not receive full TDX
289 A TD guest is in control of whether its memory accesses are treated as
290 private or shared.  It selects the behavior with a bit in its page table
292 information in shared memory, exposing it to the untrusted hypervisor.
294 #VE on Shared Memory
297 Access to shared mappings can cause a #VE.  The hypervisor ultimately
298 controls whether a shared memory access causes a #VE, so the guest must be
299 careful to only reference shared pages it can safely handle a #VE.  For
300 instance, the guest should be careful not to access shared memory in the
303 Shared mapping content is entirely controlled by the hypervisor. The guest
304 should only use shared mappings for communicating with the hypervisor.
305 Shared mappings must never be used for sensitive memory content like kernel
306 stacks.  A good rule of thumb is that hypervisor-shared memory should be
307 treated the same as memory mapped to userspace.  Both the hypervisor and
310 MMIO for virtual devices is implemented as shared memory.  The guest must
318 memory is also private memory, the kernel might theoretically need to
319 handle a #VE on arbitrary kernel memory accesses.  This is not feasible, so
320 TDX guests ensure that all guest memory has been "accepted" before memory
323 A modest amount of memory (typically 512M) is pre-accepted by the firmware
333 -----------------
350 #VE-triggering actions (discussed above) while this block is in place.
355 -------------
357 In non-TDX VMs, MMIO is usually implemented by giving a guest access to a
369 theoretically be accessed with any instruction that accesses memory.
376 Shared Memory Conversions
377 -------------------------
379 All TDX guest memory starts out as private at boot.  This memory can not
382 memory must be converted between shared and private.  This can be
383 accomplished using some existing memory encryption helpers:
385  * set_memory_decrypted() converts a range of pages to shared.
386  * set_memory_encrypted() converts memory back to private.
388 Device drivers are the primary user of shared memory, but there's no need
393 converted to shared on boot.
422 from the TDX module. TDREPORT is a fixed-size data structure generated by
423 the TDX module which contains guest-specific information (such as build
425 the integrity of the TDREPORT. A user-provided 64-Byte REPORTDATA is used
446 https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.…