xref: /cloud-hypervisor/docs/intel_tdx.md (revision eea9bcea38e0c5649f444c829f3a4f9c22aa486c) 
1# Intel TDX
2
3Intel® Trust Domain Extensions (Intel® TDX) is an Intel technology designed to
4isolate virtual machines from the VMM, hypervisor and any other software on the
5host platform.
6
7For more information about TDX technical aspects, design and specification
8please refer to the
9[TDX Homepage](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html).
10
11The required Linux changes for the host side can be found in the
12[KVM TDX tree](https://github.com/intel/tdx/tree/kvm) while the changes for
13the guest side can be found in the [Guest TDX tree](https://github.com/intel/tdx/tree/guest).
14
15The TDVF firmware can be found in the
16[EDK2 staging project](https://github.com/tianocore/edk2-staging/tree/TDVF).
17
18The TDShim firmware can be found in the
19[Confidential Containers project](https://github.com/confidential-containers/td-shim).
20
21## Cloud Hypervisor support
22
23First, you must be running on a machine with TDX enabled in hardware, and
24with the host OS compiled from the [KVM TDX tree](https://github.com/intel/tdx/tree/kvm).
25
26Cloud Hypervisor can run TDX VM (Trust Domain) by loading a TD firmware,
27which will then load the guest kernel from the image. The image must be custom
28as it must include a kernel built from the [Guest TDX tree](https://github.com/intel/tdx/tree/guest).
29
30### TDVF
31
32The firmware can be built as follows:
33
34```bash
35git clone https://github.com/tianocore/edk2-staging.git
36cd edk2-staging
37git checkout origin/TDVF
38git submodule update --init --recursive
39make -C BaseTools
40source ./edksetup.sh
41build -p OvmfPkg/OvmfCh.dsc -a X64 -t GCC5 -b RELEASE
42```
43
44If debug logs are needed, here is the alternative command:
45
46```bash
47build -p OvmfPkg/OvmfCh.dsc -a X64 -t GCC5 -D DEBUG_ON_SERIAL_PORT=TRUE
48```
49
50On the Cloud Hypervisor side, all you need is to build the project with the
51`tdx` feature enabled:
52
53```bash
54cargo build --features tdx
55```
56
57And run a TDX VM by providing the firmware previously built, along with the
58guest image containing the TDX enlightened kernel. The latest image
59`td-guest-rhel8.5.raw` contains `console=hvc0` on the kernel boot parameters,
60meaning it will be printing guest kernel logs to the `virtio-console` device.
61
62```bash
63./cloud-hypervisor \
64    --platform tdx=on
65    --firmware edk2-staging/Build/OvmfCh/RELEASE_GCC5/FV/OVMF.fd \
66    --cpus boot=1 \
67    --memory size=1G \
68    --disk path=tdx_guest_img
69```
70
71And here is the alternative command when looking for debug logs from the
72firmware:
73
74```bash
75./cloud-hypervisor \
76    --platform tdx=on
77    --firmware edk2-staging/Build/OvmfCh/DEBUG_GCC5/FV/OVMF.fd \
78    --cpus boot=1 \
79    --memory size=1G \
80    --disk path=tdx_guest_img \
81    --serial file=/tmp/ch_serial \
82    --console tty
83```
84
85### TDShim
86
87This is a lightweight version of the TDVF, written in Rust and designed for
88direct kernel boot, which is useful for containers use cases.
89
90You can find the instructions for building the firmware directly from the
91project [documentation](https://github.com/confidential-containers/td-shim/tree/staging#how-to-build).
92
93And run a TDX VM by providing the firmware previously built, along with a guest
94kernel built from the [Guest TDX tree](https://github.com/intel/tdx/tree/guest).
95The appropriate kernel boot options must be provided through the `--cmdline`
96option as well.
97
98```bash
99./cloud-hypervisor \
100    --platform tdx=on
101    --firmware tdshim \
102    --kernel bzImage \
103    --cmdline "root=/dev/vda3 console=hvc0 rw"
104    --cpus boot=1 \
105    --memory size=1G \
106    --disk path=tdx_guest_img
107```
108
109### Guest kernel limitations
110
111#### Serial ports disabled
112
113The latest guest kernel that can be found in the latest image
114`td-guest-rhel8.5.raw` disabled the support for serial ports. This means adding
115`console=ttyS0` will have no effect and will not print any log from the guest.
116
117#### PCI hotplug through ACPI
118
119Unless you run the guest kernel with the parameter `tdx_disable_filter`, ACPI
120devices responsible for handling PCI hotplug (PCI hotplug controller, PCI
121Express Bus and Generic Event Device) will not be allowed, therefore the
122corresponding drivers will not be loaded and the PCI hotplug feature will not
123be supported.
124