Debian Codegraph @

Documentation/virt/kvm/x86/intel-tdx.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================================
4 Intel Trust Domain Extensions (TDX)
5 ===================================
6
7 Overview
8 ========
9 Intel's Trust Domain Extensions (TDX) protect confidential guest VMs from the
10 host and physical attacks. A CPU-attested software module called 'the TDX
11 module' runs inside a new CPU isolated range to provide the functionalities to
12 manage and run protected VMs, a.k.a, TDX guests or TDs.
13
14 Please refer to [1] for the whitepaper, specifications and other resources.
15
16 This documentation describes TDX-specific KVM ABIs. The TDX module needs to be
17 initialized before it can be used by KVM to run any TDX guests. The host
18 core-kernel provides the support of initializing the TDX module, which is
19 described in the Documentation/arch/x86/tdx.rst.
20
21 API description
22 ===============
23
24 KVM_MEMORY_ENCRYPT_OP
25 ---------------------
26 :Type: vm ioctl, vcpu ioctl
27
28 For TDX operations, KVM_MEMORY_ENCRYPT_OP is re-purposed to be generic
29 ioctl with TDX specific sub-ioctl() commands.
30
31 ::
32
33 /* Trust Domain Extensions sub-ioctl() commands. */
34 enum kvm_tdx_cmd_id {
35 KVM_TDX_CAPABILITIES = 0,
36 KVM_TDX_INIT_VM,
37 KVM_TDX_INIT_VCPU,
38 KVM_TDX_INIT_MEM_REGION,
39 KVM_TDX_FINALIZE_VM,
40 KVM_TDX_GET_CPUID,
41
42 KVM_TDX_CMD_NR_MAX,
43 };
44
45 struct kvm_tdx_cmd {
46 /* enum kvm_tdx_cmd_id */
47 __u32 id;
48 /* flags for sub-command. If sub-command doesn't use this, set zero. */
49 __u32 flags;
50 /*
51 * data for each sub-command. An immediate or a pointer to the actual
52 * data in process virtual address. If sub-command doesn't use it,
53 * set zero.
54 */
55 __u64 data;
56 /*
57 * Auxiliary error code. The sub-command may return TDX SEAMCALL
58 * status code in addition to -Exxx.
59 */
60 __u64 hw_error;
61 };
62
63 KVM_TDX_CAPABILITIES
64 --------------------
65 :Type: vm ioctl
66 :Returns: 0 on success, <0 on error
67
68 Return the TDX capabilities that current KVM supports with the specific TDX
69 module loaded in the system. It reports what features/capabilities are allowed
70 to be configured to the TDX guest.
71
72 - id: KVM_TDX_CAPABILITIES
73 - flags: must be 0
74 - data: pointer to struct kvm_tdx_capabilities
75 - hw_error: must be 0
76
77 ::
78
79 struct kvm_tdx_capabilities {
80 __u64 supported_attrs;
81 __u64 supported_xfam;
82
83 /* TDG.VP.VMCALL hypercalls executed in kernel and forwarded to
84 * userspace, respectively
85 */
86 __u64 kernel_tdvmcallinfo_1_r11;
87 __u64 user_tdvmcallinfo_1_r11;
88
89 /* TDG.VP.VMCALL instruction executions subfunctions executed in kernel
90 * and forwarded to userspace, respectively
91 */
92 __u64 kernel_tdvmcallinfo_1_r12;
93 __u64 user_tdvmcallinfo_1_r12;
94
95 __u64 reserved[250];
96
97 /* Configurable CPUID bits for userspace */
98 struct kvm_cpuid2 cpuid;
99 };
100
101
102 KVM_TDX_INIT_VM
103 ---------------
104 :Type: vm ioctl
105 :Returns: 0 on success, <0 on error
106
107 Perform TDX specific VM initialization. This needs to be called after
108 KVM_CREATE_VM and before creating any VCPUs.
109
110 - id: KVM_TDX_INIT_VM
111 - flags: must be 0
112 - data: pointer to struct kvm_tdx_init_vm
113 - hw_error: must be 0
114
115 ::
116
117 struct kvm_tdx_init_vm {
118 __u64 attributes;
119 __u64 xfam;
120 __u64 mrconfigid[6]; /* sha384 digest */
121 __u64 mrowner[6]; /* sha384 digest */
122 __u64 mrownerconfig[6]; /* sha384 digest */
123
124 /* The total space for TD_PARAMS before the CPUIDs is 256 bytes */
125 __u64 reserved[12];
126
127 /*
128 * Call KVM_TDX_INIT_VM before vcpu creation, thus before
129 * KVM_SET_CPUID2.
130 * This configuration supersedes KVM_SET_CPUID2s for VCPUs because the
131 * TDX module directly virtualizes those CPUIDs without VMM. The user
132 * space VMM, e.g. qemu, should make KVM_SET_CPUID2 consistent with
133 * those values. If it doesn't, KVM may have wrong idea of vCPUIDs of
134 * the guest, and KVM may wrongly emulate CPUIDs or MSRs that the TDX
135 * module doesn't virtualize.
136 */
137 struct kvm_cpuid2 cpuid;
138 };
139
140
141 KVM_TDX_INIT_VCPU
142 -----------------
143 :Type: vcpu ioctl
144 :Returns: 0 on success, <0 on error
145
146 Perform TDX specific VCPU initialization.
147
148 - id: KVM_TDX_INIT_VCPU
149 - flags: must be 0
150 - data: initial value of the guest TD VCPU RCX
151 - hw_error: must be 0
152
153 KVM_TDX_INIT_MEM_REGION
154 -----------------------
155 :Type: vcpu ioctl
156 :Returns: 0 on success, <0 on error
157
158 Initialize @nr_pages TDX guest private memory starting from @gpa with userspace
159 provided data from @source_addr. @source_addr must be PAGE_SIZE-aligned.
160
161 Note, before calling this sub command, memory attribute of the range
162 [gpa, gpa + nr_pages] needs to be private. Userspace can use
163 KVM_SET_MEMORY_ATTRIBUTES to set the attribute.
164
165 If KVM_TDX_MEASURE_MEMORY_REGION flag is specified, it also extends measurement.
166
167 - id: KVM_TDX_INIT_MEM_REGION
168 - flags: currently only KVM_TDX_MEASURE_MEMORY_REGION is defined
169 - data: pointer to struct kvm_tdx_init_mem_region
170 - hw_error: must be 0
171
172 ::
173
174 #define KVM_TDX_MEASURE_MEMORY_REGION (1UL << 0)
175
176 struct kvm_tdx_init_mem_region {
177 __u64 source_addr;
178 __u64 gpa;
179 __u64 nr_pages;
180 };
181
182
183 KVM_TDX_FINALIZE_VM
184 -------------------
185 :Type: vm ioctl
186 :Returns: 0 on success, <0 on error
187
188 Complete measurement of the initial TD contents and mark it ready to run.
189
190 - id: KVM_TDX_FINALIZE_VM
191 - flags: must be 0
192 - data: must be 0
193 - hw_error: must be 0
194
195
196 KVM_TDX_GET_CPUID
197 -----------------
198 :Type: vcpu ioctl
199 :Returns: 0 on success, <0 on error
200
201 Get the CPUID values that the TDX module virtualizes for the TD guest.
202 When it returns -E2BIG, the user space should allocate a larger buffer and
203 retry. The minimum buffer size is updated in the nent field of the
204 struct kvm_cpuid2.
205
206 - id: KVM_TDX_GET_CPUID
207 - flags: must be 0
208 - data: pointer to struct kvm_cpuid2 (in/out)
209 - hw_error: must be 0 (out)
210
211 ::
212
213 struct kvm_cpuid2 {
214 __u32 nent;
215 __u32 padding;
216 struct kvm_cpuid_entry2 entries[0];
217 };
218
219 struct kvm_cpuid_entry2 {
220 __u32 function;
221 __u32 index;
222 __u32 flags;
223 __u32 eax;
224 __u32 ebx;
225 __u32 ecx;
226 __u32 edx;
227 __u32 padding[3];
228 };
229
230 KVM TDX creation flow
231 =====================
232 In addition to the standard KVM flow, new TDX ioctls need to be called. The
233 control flow is as follows:
234
235 #. Check system wide capability
236
237 * KVM_CAP_VM_TYPES: Check if VM type is supported and if KVM_X86_TDX_VM
238 is supported.
239
240 #. Create VM
241
242 * KVM_CREATE_VM
243 * KVM_TDX_CAPABILITIES: Query TDX capabilities for creating TDX guests.
244 * KVM_CHECK_EXTENSION(KVM_CAP_MAX_VCPUS): Query maximum VCPUs the TD can
245 support at VM level (TDX has its own limitation on this).
246 * KVM_SET_TSC_KHZ: Configure TD's TSC frequency if a different TSC frequency
247 than host is desired. This is Optional.
248 * KVM_TDX_INIT_VM: Pass TDX specific VM parameters.
249
250 #. Create VCPU
251
252 * KVM_CREATE_VCPU
253 * KVM_TDX_INIT_VCPU: Pass TDX specific VCPU parameters.
254 * KVM_SET_CPUID2: Configure TD's CPUIDs.
255 * KVM_SET_MSRS: Configure TD's MSRs.
256
257 #. Initialize initial guest memory
258
259 * Prepare content of initial guest memory.
260 * KVM_TDX_INIT_MEM_REGION: Add initial guest memory.
261 * KVM_TDX_FINALIZE_VM: Finalize the measurement of the TDX guest.
262
263 #. Run VCPU
264
265 References
266 ==========
267
268 https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html