SecurityPkg: Add TPM PTP support in TCG2 SMM.

[mirror_edk2.git] / OvmfPkg / README

diff --git a/OvmfPkg/README b/OvmfPkg/README
index 44942e67eab536f418da374d257a1be324039306..e6137ddc1f3695f07471d93fe53bb2a8829f43f0 100644 (file)
--- a/OvmfPkg/README
+++ b/OvmfPkg/README
@@ -5,7 +5,7 @@ The Open Virtual Machine Firmware (OVMF) project aims
 to support firmware for Virtual Machines using the edk2\r
 code base.  More information can be found at:\r
 \r
-http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF\r
+http://www.tianocore.org/ovmf/\r
 \r
 === STATUS ===\r
 \r
@@ -55,7 +55,7 @@ these binary outputs:
 \r
 More information on building OVMF can be found at:\r
 \r
-http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=How_to_build_OVMF\r
+https://github.com/tianocore/tianocore.github.io/wiki/How%20to%20build%20OVMF\r
 \r
 === RUNNING OVMF on QEMU ===\r
 \r
@@ -66,6 +66,8 @@ http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=How_to_build_OVM
   - Option 1: QEMU 1.6 or newer; Use QEMU -pflash parameter\r
     * QEMU/OVMF will use emulated flash, and fully support UEFI variables\r
     * Run qemu with: -pflash path/to/OVMF.fd\r
+    * Note that this option is required for running SecureBoot-enabled builds\r
+      (-D SECURE_BOOT_ENABLE).\r
   - Option 2: Use QEMU -bios parameter\r
     * Note that UEFI variables will be partially emulated, and non-volatile\r
       variables may lose their contents after a reboot\r
@@ -116,6 +118,58 @@ $ OvmfPkg/build.sh -a X64 qemu -cdrom /path/to/disk-image.iso
 To build a 32-bit OVMF without debug messages using GCC 4.5:\r
 $ OvmfPkg/build.sh -a IA32 -b RELEASE -t GCC45\r
 \r
+=== SMM support ===\r
+\r
+Requirements:\r
+* SMM support requires QEMU 2.5.\r
+* The minimum required QEMU machine type is "pc-q35-2.5".\r
+* SMM with KVM requires Linux 4.4 (host).\r
+\r
+OVMF is capable of utilizing SMM if the underlying QEMU or KVM hypervisor\r
+emulates SMM. SMM is put to use in the S3 suspend and resume infrastructure,\r
+and in the UEFI variable driver stack. The purpose is (virtual) hardware\r
+separation between the runtime guest OS and the firmware (OVMF), with the\r
+intent to make Secure Boot actually secure, by preventing the runtime guest OS\r
+from tampering with the variable store and S3 areas.\r
+\r
+For SMM support, OVMF must be built with the "-D SMM_REQUIRE" option. The\r
+resultant firmware binary will check if QEMU actually provides SMM emulation;\r
+if it doesn't, then OVMF will log an error and trigger an assertion failure\r
+during boot (even in RELEASE builds). Both the naming of the flag (SMM_REQUIRE,\r
+instead of SMM_ENABLE), and this behavior are consistent with the goal\r
+described above: this is supposed to be a security feature, and fallbacks are\r
+not allowed. Similarly, a pflash-backed variable store is a requirement.\r
+\r
+QEMU should be started with the options listed below (in addition to any other\r
+guest-specific flags). The command line should be gradually composed from the\r
+hints below. '\' is used to extend the command line to multiple lines, and '^'\r
+can be used on Windows.\r
+\r
+* QEMU binary and options specific to 32-bit guests:\r
+\r
+  $ qemu-system-i386 -cpu coreduo,-nx \\r
+\r
+  or\r
+\r
+  $ qemu-system-x86_64 -cpu <MODEL>,-lm,-nx \\r
+\r
+* QEMU binary for running 64-bit guests (no particular options):\r
+\r
+  $ qemu-system-x86_64 \\r
+\r
+* Flags common to all SMM scenarios (only the Q35 machine type is supported):\r
+\r
+  -machine q35,smm=on,accel=(tcg|kvm) \\r
+  -m ... \\r
+  -smp ... \\r
+  -global driver=cfi.pflash01,property=secure,value=on \\r
+  -drive if=pflash,format=raw,unit=0,file=OVMF_CODE.fd,readonly=on \\r
+  -drive if=pflash,format=raw,unit=1,file=copy_of_OVMF_VARS.fd \\r
+\r
+* In order to disable S3, add:\r
+\r
+  -global ICH9-LPC.disable_s3=1 \\r
+\r
 === Network Support ===\r
 \r
 OVMF provides a UEFI network stack by default. Its lowest level driver is the\r