lkml.org 
[lkml]   [2022]   [Jul]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
Subject[intel-tdx:kvm-upstream 266/267] htmldocs: Documentation/virt/kvm/intel-tdx.rst:181: WARNING: Enumerated list ends without a blank line; unexpected unindent.
tree:   https://github.com/intel/tdx.git kvm-upstream
head: 7af4efe32638544aecb58ed7365d0ef2ea6f85ea
commit: 9e54fa1ac03df3cd2fb7a2e64d3cffc35d4f097e [266/267] Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)
reproduce: make htmldocs

If you fix the issue, kindly add following tag where applicable
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> Documentation/virt/kvm/intel-tdx.rst:181: WARNING: Enumerated list ends without a blank line; unexpected unindent.
>> Documentation/virt/kvm/intel-tdx.rst:219: WARNING: Unexpected indentation.
>> Documentation/virt/kvm/intel-tdx.rst:223: WARNING: Block quote ends without a blank line; unexpected unindent.
>> Documentation/virt/kvm/intel-tdx.rst:239: WARNING: Bullet list ends without a blank line; unexpected unindent.
>> Documentation/virt/kvm/intel-tdx.rst:353: WARNING: Footnote [1] is not referenced.
>> Documentation/virt/kvm/intel-tdx.rst: WARNING: document isn't included in any toctree

vim +181 Documentation/virt/kvm/intel-tdx.rst

179
180 #. system wide capability check
> 181 * KVM_CAP_VM_TYPES: check if VM type is supported and if TDX_VM_TYPE is
182 supported.
183
184 #. creating VM
185 * KVM_CREATE_VM
186 * KVM_TDX_CAPABILITIES: query if TDX is supported on the platform.
187 * KVM_TDX_INIT_VM: pass TDX specific VM parameters.
188
189 #. creating VCPU
190 * KVM_CREATE_VCPU
191 * KVM_TDX_INIT_VCPU: pass TDX specific VCPU parameters.
192
193 #. initializing guest memory
194 * allocate guest memory and initialize page same to normal KVM case
195 In TDX case, parse and load TDVF into guest memory in addition.
196 * KVM_TDX_INIT_MEM_REGION to add and measure guest pages.
197 If the pages has contents above, those pages need to be added.
198 Otherwise the contents will be lost and guest sees zero pages.
199 * KVM_TDX_FINALIAZE_VM: Finalize VM and measurement
200 This must be after KVM_TDX_INIT_MEM_REGION.
201
202 #. run vcpu
203
204 Design discussion
205 =================
206
207 Coexistence of normal(VMX) VM and TD VM
208 ---------------------------------------
209 It's required to allow both legacy(normal VMX) VMs and new TD VMs to
210 coexist. Otherwise the benefits of VM flexibility would be eliminated.
211 The main issue for it is that the logic of kvm_x86_ops callbacks for
212 TDX is different from VMX. On the other hand, the variable,
213 kvm_x86_ops, is global single variable. Not per-VM, not per-vcpu.
214
215 Several points to be considered.
216 . No or minimal overhead when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
217 . Avoid overhead of indirect call via function pointers.
218 . Contain the changes under arch/x86/kvm/vmx directory and share logic
> 219 with VMX for maintenance.
220 Even though the ways to operation on VM (VMX instruction vs TDX
221 SEAM call) is different, the basic idea remains same. So, many
222 logic can be shared.
> 223 . Future maintenance
224 The huge change of kvm_x86_ops in (near) future isn't expected.
225 a centralized file is acceptable.
226
227 - Wrapping kvm x86_ops: The current choice
228 Introduce dedicated file for arch/x86/kvm/vmx/main.c (the name,
229 main.c, is just chosen to show main entry points for callbacks.) and
230 wrapper functions around all the callbacks with
231 "if (is-tdx) tdx-callback() else vmx-callback()".
232
233 Pros:
234 - No major change in common x86 KVM code. The change is (mostly)
235 contained under arch/x86/kvm/vmx/.
236 - When TDX is disabled(CONFIG_INTEL_TDX_HOST=n), the overhead is
237 optimized out.
238 - Micro optimization by avoiding function pointer.
> 239 Cons:
240 - Many boiler plates in arch/x86/kvm/vmx/main.c.
241
242 Alternative:
243 - Introduce another callback layer under arch/x86/kvm/vmx.
244 Pros:
245 - No major change in common x86 KVM code. The change is (mostly)
246 contained under arch/x86/kvm/vmx/.
247 - clear separation on callbacks.
248 Cons:
249 - overhead in VMX even when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
250
251 - Allow per-VM kvm_x86_ops callbacks instead of global kvm_x86_ops
252 Pros:
253 - clear separation on callbacks.
254 Cons:
255 - Big change in common x86 code.
256 - overhead in common code even when TDX is
257 disabled(CONFIG_INTEL_TDX_HOST=n).
258
259 - Introduce new directory arch/x86/kvm/tdx
260 Pros:
261 - It clarifies that TDX is different from VMX.
262 Cons:
263 - Given the level of code sharing, it complicates code sharing.
264
265 KVM MMU Changes
266 ---------------
267 KVM MMU needs to be enhanced to handle Secure/Shared-EPT. The
268 high-level execution flow is mostly same to normal EPT case.
269 EPT violation/misconfiguration -> invoke TDP fault handler ->
270 resolve TDP fault -> resume execution. (or emulate MMIO)
271 The difference is, that S-EPT is operated(read/write) via TDX SEAM
272 call which is expensive instead of direct read/write EPT entry.
273 One bit of GPA (51 or 47 bit) is repurposed so that it means shared
274 with host(if set to 1) or private to TD(if cleared to 0).
275
276 - The current implementation
277 . Reuse the existing MMU code with minimal update. Because the
278 execution flow is mostly same. But additional operation, TDX call
279 for S-EPT, is needed. So add hooks for it to kvm_x86_ops.
280 . For performance, minimize TDX SEAM call to operate on S-EPT. When
281 getting corresponding S-EPT pages/entry from faulting GPA, don't
282 use TDX SEAM call to read S-EPT entry. Instead create shadow copy
283 in host memory.
284 Repurpose the existing kvm_mmu_page as shadow copy of S-EPT and
285 associate S-EPT to it.
286 . Treats share bit as attributes. mask/unmask the bit where
287 necessary to keep the existing traversing code works.
288 Introduce kvm.arch.gfn_shared_mask and use "if (gfn_share_mask)"
289 for special case.
290 = 0 : for non-TDX case
291 = 51 or 47 bit set for TDX case.
292
293 Pros:
294 - Large code reuse with minimal new hooks.
295 - Execution path is same.
296 Cons:
297 - Complicates the existing code.
298 - Repurpose kvm_mmu_page as shadow of Secure-EPT can be confusing.
299
300 Alternative:
301 - Replace direct read/write on EPT entry with TDX-SEAM call by
302 introducing callbacks on EPT entry.
303 Pros:
304 - Straightforward.
305 Cons:
306 - Too many touching point.
307 - Too slow due to TDX-SEAM call.
308 - Overhead even when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
309
310 - Sprinkle "if (is-tdx)" for TDX special case
311 Pros:
312 - Straightforward.
313 Cons:
314 - The result is non-generic and ugly.
315 - Put TDX specific logic into common KVM MMU code.
316
317 New KVM API, ioctl (sub)command, to manage TD VMs
318 -------------------------------------------------
319 Additional KVM API are needed to control TD VMs. The operations on TD
320 VMs are specific to TDX.
321
322 - Piggyback and repurpose KVM_MEMORY_ENCRYPT_OP
323 Although not all operation isn't memory encryption, repupose to get
324 TDX specific ioctls.
325 Pros:
326 - No major change in common x86 KVM code.
327 Cons:
328 - The operations aren't actually memory encryption, but operations
329 on TD VMs.
330
331 Alternative:
332 - Introduce new ioctl for guest protection like
333 KVM_GUEST_PROTECTION_OP and introduce subcommand for TDX.
334 Pros:
335 - Clean name.
336 Cons:
337 - One more new ioctl for guest protection.
338 - Confusion with KVM_MEMORY_ENCRYPT_OP with KVM_GUEST_PROTECTION_OP.
339
340 - Rename KVM_MEMORY_ENCRYPT_OP to KVM_GUEST_PROTECTION_OP and keep
341 KVM_MEMORY_ENCRYPT_OP as same value for user API for compatibility.
342 "#define KVM_MEMORY_ENCRYPT_OP KVM_GUEST_PROTECTION_OP" for uapi
343 compatibility.
344 Pros:
345 - No new ioctl with more suitable name.
346 Cons:
347 - May cause confusion to the existing user program.
348
349
350 References
351 ==========
352
> 353 .. [1] TDX specification
354 https://software.intel.com/content/www/us/en/develop/articles/intel-trust-domain-extensions.html
355 .. [2] Intel Trust Domain Extensions (Intel TDX)
356 https://software.intel.com/content/dam/develop/external/us/en/documents/tdx-whitepaper-final9-17.pdf
357 .. [3] Intel CPU Architectural Extensions Specification
358 https://software.intel.com/content/dam/develop/external/us/en/documents/intel-tdx-cpu-architectural-specification.pdf
359 .. [4] Intel TDX Module 1.0 EAS
360 https://software.intel.com/content/dam/develop/external/us/en/documents/intel-tdx-module-1eas.pdf
361 .. [5] Intel TDX Loader Interface Specification
362 https://software.intel.com/content/dam/develop/external/us/en/documents/intel-tdx-seamldr-interface-specification.pdf
363 .. [6] Intel TDX Guest-Hypervisor Communication Interface
364 https://software.intel.com/content/dam/develop/external/us/en/documents/intel-tdx-guest-hypervisor-communication-interface.pdf
365 .. [7] Intel TDX Virtual Firmware Design Guide
366 https://software.intel.com/content/dam/develop/external/us/en/documents/tdx-virtual-firmware-design-guide-rev-1.
367 .. [8] intel public github
368 kvm TDX branch: https://github.com/intel/tdx/tree/kvm
369 TDX guest branch: https://github.com/intel/tdx/tree/guest
370 .. [9] tdvf
371 https://github.com/tianocore/edk2-staging/tree/TDVF
> 372 .. [10] KVM forum 2020: Intel Virtualization Technology Extensions to

--
0-DAY CI Kernel Test Service
https://01.org/lkp

\
 
 \ /
  Last update: 2022-07-04 22:31    [W:0.050 / U:1.392 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site