Re: [Qemu-devel] [PATCH v4 4/5] acpi: build TPM Physical Presence interface

[Stefan Berger]

diff --git a/docs/specs/tpm.txt b/docs/specs/tpm.txt
index c230c4c93e..90f96c53cb 100644
--- a/docs/specs/tpm.txt
+++ b/docs/specs/tpm.txt
@@ -42,6 +42,85 @@ URL:

 https://trustedcomputinggroup.org/tcg-acpi-specification/

+== ACPI PPI Interface ==
+
+QEMU supports the Physical Presence Interface (PPI) for TPM 1.2 and TPM 
2. This
+interface requires ACPI and firmware support. The specification can be 
found at
+the following URL:
+
+https://trustedcomputinggroup.org/resource/tcg-physical-presence-interface-specification/
+
+PPI enables a system administrator (root) to request a modification to the
+TPM upon reboot. The PPI specification defines the operation requests 
and the
+actions the firmware has to take. The system administrator passes the 
operation
+request number to the firmware through an ACPI interface which writes this
+number to a memory location that the firmware knows. Upon reboot, the 
firmware
+finds the number and sends commands to the the TPM. The firmware writes 
the TPM
+result code and the operation request number to a memory location that 
ACPI can
+read from and pass the result on to the administrator.
+
+The PPI specification defines a set of mandatory and optional 
operations for
+the firmware to implement. The ACPI interface also allows an 
administrator to
+list the supported operations. In QEMU the ACPI code is generated by 
QEMU, yet
+the firmware needs to implement support on a per-operations basis, and
+different firmwares may support a different subset. Therefore, QEMU 
introduces
+the virtual memory device for PPI where the firmware can indicate which
+operations it supports and ACPI can enable the ones that are supported and
+disable all others. This interface lies in main memory and has the 
following
+layout:
+
+ +----------+--------+--------+-------------------------------------------+
+   |  Field   | Length | Offset | Description               |
+ +----------+--------+--------+-------------------------------------------+
+   | func     |  0x100 |  0x000 | Firmware sets values for each 
supported   |
+   |          |        |        | operation. See defined values 
below.      |
+ +----------+--------+--------+-------------------------------------------+
+   | ppin     |   0x1  |  0x100 | SMI interrupt to use. Set by 
firmware.    |
+   |          |        |        | Not 
supported.                            |
+ +----------+--------+--------+-------------------------------------------+
+   | ppip     |   0x4  |  0x101 | ACPI function index to pass to SMM 
code.  |
+   |          |        |        | Set by ACPI. Not 
supported.               |
+ +----------+--------+--------+-------------------------------------------+
+   | pprp     |   0x4  |  0x105 | Result of last executed operation. 
Set by |
+   |          |        |        | firmware. See function index 5 for 
values.|
+ +----------+--------+--------+-------------------------------------------+
+   | pprq     |   0x4  |  0x109 | Operation request number to execute. 
See  |
+   |          |        |        | 'Physical Presence Interface 
Operation    |
+   |          |        |        | Summary' tables in specs. Set by 
ACPI.    |
+ +----------+--------+--------+-------------------------------------------+
+   | pprm     |   0x4  |  0x10d | Operation request optional 
parameter.     |
+   |          |        |        | Values depend on operation. Set by 
ACPI.  |
+ +----------+--------+--------+-------------------------------------------+
+   | lppr     |   0x4  |  0x111 | Last executed operation request 
number.   |
+   |          |        |        | Copied from pprq field by 
firmware.       |
+ +----------+--------+--------+-------------------------------------------+
+   | fret     |   0x4  |  0x115 | Result code from SMM 
function.            |
+   |          |        |        | Not 
supported.                            |
+ +----------+--------+--------+-------------------------------------------+
+   | res1     |  0x40  |  0x119 | Reserved for future 
use                   |
+ +----------+--------+--------+-------------------------------------------+
+   | next_step|   0x1  |  0x159 | Operation to execute after reboot 
by      |
+   |          |        |        | firmware. Used by 
firmware.               |
+ +----------+--------+--------+-------------------------------------------+
+
+   The following values are supported for the 'func' field. They correspond
+   to the values used by ACPI function index 8.
+
+ +----------+-------------------------------------------------------------+
+   | value    | 
Description                                                 |
+ +----------+-------------------------------------------------------------+
+   | 0        | Operation is not 
implemented.                               |
+ +----------+-------------------------------------------------------------+
+   | 1        | Operation is only accessible through 
firmware.              |
+ +----------+-------------------------------------------------------------+
+   | 2        | Operation is blocked for OS by firmware 
configuration.      |
+ +----------+-------------------------------------------------------------+
+   | 3        | Operation is allowed and physically present user 
required.  |
+ +----------+-------------------------------------------------------------+
+   | 4        | Operation is allowed and physically present user is 
not     |
+   |          | 
required.                                                   |
+ +----------+-------------------------------------------------------------+
+

 QEMU files related to TPM ACPI tables:
  - hw/i386/acpi-build.c