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@xxxxxxxxx> 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
