diff --git a/Virtualization/bk_main.xml b/Virtualization/bk_main.xml
index 78063cd..cc943ec 100644
--- a/Virtualization/bk_main.xml
+++ b/Virtualization/bk_main.xml
@@ -334,6 +334,7 @@
+
diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml
index 7ecc34d..3ef6cc0 100644
--- a/Virtualization/ch_virtual_io.xml
+++ b/Virtualization/ch_virtual_io.xml
@@ -19604,4 +19604,361 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
+
+
+ Virtual Trusted Platform Module (VTPM)
+
+ This section defines the Virtual Trusted Platform Module (VTPM) option.
+ Firmware can provide the service of a VTPM device to a partition using the
+ mechanisms of the Reliable Command/Response Transport and Logical Remote DMA
+ of the Synchronous VIO Infrastructure. A VTPM device primarily allows VTPM
+ aware system firmware and operating systems to perform a trusted boot.
+
+ The VTPM architecture is built upon the architecture specified in the
+ following sections:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VTPM General
+
+ This informative section provides an outline of the architectural intent
+ of the use of the VTPM.
+
+ The platform, through the partition definition can define multiple VTPMs,
+ and ensures that only a single VTPM is associated with a partition.
+
+ The client partition may be assigned various virtual adapters, each with
+ a corresponding node in the device tree. The node's
+ “device_type” and
+ “compatible”
+ properties may be used to distinguish between adapter types and thus locate a
+ VTPM. The node's unit address is an invariant handle to the
+ adapter and given by the
+ “reg” property.
+ The “ibm,my-dma-window”
+ property encodes the adapter's LIOBN and RTCE table size for use with the
+ CRQ and LDRMA mechanisms. The CRQ's assigned interrupt source number is given
+ by the node's
+ “interrupt” property.
+
+ The presence of a VTPM device tree node causes the client to load a
+ device driver associated with the node's
+ “compatible” property.
+ The driver first allocates and pins memory for the CRQ - an array of
+ 16 byte elements, large enough to contain all possible responses.
+ The queue is then RTCE mapped using the H_PUT_TCE hcall and the values of the
+ “ibm,my-dma-window” property.
+ The CRQ is registered via the H_REG_CRQ hcall,
+ and the partition may request interrupt notification using the source given by the
+ “interrupt” property.
+
+ The driver then follows the VTPM initialization steps as described in
+
+ resulting in the allocation and RTCE mapping of memory buffers with which to send/receive TPM commands and responses of the format described in the Trusted Computing Group TPM Specification, version 1.2 [29]. Once initialized the client may send commands by writing them directly to the RTCE-mapped memory buffer and issuing the H_SEND_CRQ hcall with the buffer's I/O address. If successful, the driver awaits an interrupt indicating that a response to the command is available – and is present in the same buffer used for command transmission. Notice that the client does not use LRDMA facilities itself, firmware is the only entity to copy data.
+
+
+
+
+ VTPM Requirements
+
+ This normative section provides the general requirements for the support of VTPM.
+
+
+
+
+
+ R1--2.
+
+
+ For the VTPM option: The platform must implement the
+ Reliable Command/Response Transport option as defined in
+ .
+
+
+
+
+ R1--3.
+
+
+ For the VTPM option: The platform must implement the
+ Logical Remote DMA option as defined in
+ .
+
+
+
+
+ In addition to the firmware primitives, and the structures they define,
+ the partition’s OS needs to know specific information regarding the configuration
+ of the virtual IOA’s that it has been assigned so that it can load and configure
+ the correct device driver code. This information is provided by the OF device
+ tree node associated with the virtual IOA
+ ().
+
+
+ Properties of the <emphasis role="bold"><literal>vtpm</literal></emphasis> Node in the OF Device Tree
+
+
+
+
+
+
+
+
+ Property Name
+
+
+
+
+ Required?
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+
+ “name”
+
+
+
+ Y
+
+
+ Standard property name per
+ , specifying the
+ virtual device name, the value shall be
+ “vtpm”.
+
+
+
+
+
+ “device_type”
+
+
+
+ Y
+
+
+ Standard property name per
+ , specifying the
+ virtual device type, the value shall be
+ “IBM,vtpm”.
+
+
+
+
+
+ “compatible”
+
+
+
+ Y
+
+
+ Standard property name per
+ , specifying the
+ programming models that are compatible with this virtual IOA, the value shall be either
+ “IBM,vtpm”
+ for VTPM version 1.2 or
+ “IBM,vtpm20”
+ for VTPM version 2.0.
+
+
+
+
+
+ “reg”
+
+
+
+ Y
+
+
+ Standard property name per
+ , specifying the unit
+ address (unit ID) associated with this virtual IOA presented as
+ an encoded array as with
+ encode-phys of length
+ “#address-cells” value shall be
+ 0xwhatever (virtual
+ “reg” property used for unit
+ address no actual locations used, therefore, the size field has
+ zero cells (does not exist) as determined by the value of the
+ “#size-cells” property).
+
+
+
+
+
+ “interrupts”
+
+
+
+ Y
+
+
+
+ Standard property name specifying the interrupt source
+ number and sense code associated with this virtual IOA
+ presented as an encoded array of two cells encoded as with
+ encode-int with the first cell containing
+ the interrupt source number, and the second cell containing the
+ sense code 0 indicating positive edge triggered. The interrupt
+ source number being the value returned by the H_XIRR or H_IPOLL
+ hcall().
+
+
+
+
+
+ “ibm,phandle”
+
+
+
+ Y
+
+
+ Device's phandle encoded with
+ encode-int –
+ present only if DRC is enabled..
+
+
+
+
+
+ “ibm,my-drc-index”
+
+
+
+ For DR
+
+
+ The integer index for the connector between the device and
+ its parent – present only if DRC is enabled.
+
+
+
+
+
+ “ibm,#dma-address-cells”
+
+
+
+ See definition column
+
+
+ Property name, to define the package’s dma address
+ format. The property value specifies the number of cells that are used
+ to encode the physical address field of dma-window properties. This
+ property is present when the dma address format cannot be derived
+ using the method described in the definition for the
+ “ibm,#dma-address-cells” property
+ in
+ .
+
+
+
+
+
+ “ibm,#dma-size-cells”
+
+
+
+ See definition column
+
+
+ Property name, to define the package’s dma address
+ size format. The property value specifies the number of cells
+ that are used to encode the size field of dma-window
+ properties. This property is present when the dma address size
+ format cannot be derived using the method described in the
+ definition for the
+ “ibm,#dma-size-cells” property
+ in
+ .
+
+
+
+
+
+ “ibm,my-dma-window”
+
+
+
+ Y
+
+
+ Property name specifying the DMA window associated with
+ this virtual IOA presented as an encoded array of three values
+ (LIOBN, phys, size).
+
+
+
+
+
+ “ibm,loc-code”
+
+
+
+ Y
+
+
+ Property name specifying the unique and persistent location
+ code associated with this virtual IOA.
+
+
+
+
+ “ibm,adjunct-virtual-addresses”
+
+
+ Y
+
+
+ Vendor unique property name indicating ranges of the client program virtual address space that are used by the virtual device serving partition adjunct.
+ See information about the children
+ of the /vdevice node.
+
+
+
+
+
+
+
+
diff --git a/Virtualization/ch_virtual_tpm.xml b/Virtualization/ch_virtual_tpm.xml
new file mode 100644
index 0000000..4a7b822
--- /dev/null
+++ b/Virtualization/ch_virtual_tpm.xml
@@ -0,0 +1,2372 @@
+
+
+
+ Virtual Trusted Platform Module (VTPM)
+
+
+ A protocol for VTPM communications
+ The protocol defined in this section is to be used with the VTPM as defined in
+ .
+ The VTPM provides the services of a TPM device to an associated client partition,
+ the primary use of a VTPM is to enable software in the partition to perform a
+ trusted boot.
+
+ This protocol is designed to fulfil the following requirements:
+
+
+
+ Extensible protocol for future functional additions.
+
+
+ Allow client partition to perform RAS operations.
+
+
+
+
+ Protocol Overview
+
+ The protocol uses both the CRQ facility and Logical Remote DMA (LRDMA) as defined in
+
+ to enable bidirectional data movement between the client partition and VTPM.
+ The client of the VTPM is required to create a CRQ buffer using information
+ found in the device tree and for full utilization of the VTPM a TCE mapped
+ buffer into which it can form TPM commands and receive TPM responses or at
+ the clients request receive RAS data.
+
+ The protocol defines four CRQ message formats, with all formats requiring
+ byte 0 to be set as per the CRQ architecture. The protocol architects that
+ byte 1 of all message formats is the “message type” field. The message type
+ indicates whether the message is a request or a response. All response message
+ types are the value of the request with the value 0x80 logically ORed.
+ Note that dependent on error checking the response may be an error message and
+ not the associated response message. All VTPM message types are listed in
+ . The four message formats used by
+ the VTPM protocol are defined in the following tables:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The CRQ buffer can be considered the VTPM's work queue, the VTPM works
+ sequentially and serially through messages in the queue. When a message is
+ de-queued and processed no new messages are processed until a response has
+ been sent. If the client wishes to have multiple TPM command messages on the
+ queue then separate TCE mapped buffers are required, the management of the
+ client partitions TCE buffers is out of the scope of this document.
+
+ Once a VTPM is associated with a partition, the VTPM will persist until the
+ partition is deleted or the VTPM is deleted. The partition can be power-cycled,
+ hibernated and migrated to a compatible platform without losing VTPM state.
+ Whilst the partition is operating client code is free to register and free the
+ CRQ buffer and TCE mapped memory without changing the state of the VTPM.
+ Client code can utilize this feature to have independent components of an
+ O/S boot, use the VTPM then perform resource clean-up before handing over
+ control to a new component without VTPM state being lost. Additionally to the
+ clients ability to register and free resources the VTPM may at any time also
+ free and re-register the CRQ if firmware requires this, therefore the client
+ may receive multiple CRQ initialization messages. Every CRQ initialization
+ message received by either the VTPM or client is handled as defined in
+ .
+
+ If the VTPM encounters a critical error and cannot continue without risk
+ to trust and integrity, the fail state is entered to which no command
+ rocessing occurs except for a best effort handling of RAS messages.
+ The fail state is documented in
+ .
+
+
+ VTPM Message Types
+
+
+
+
+
+
+
+
+
+
+
+ Message Type
+
+
+
+
+ Value
+
+
+
+
+ Sent By
+
+
+
+
+ CRQ Format Type
+
+
+
+
+ Description
+
+
+
+
+ Location
+
+
+
+
+
+
+
+ GET_VERSION
+
+
+ 0x01
+
+
+ Client Partition
+
+
+ 1
+
+
+ Obtains the version of the VTPM.
+
+
+
+
+
+
+
+ TPM_COMMAND
+
+
+ 0x02
+
+
+ Client Partition
+
+
+ 1
+
+
+ Informs the VTPM that a TPM command is ready for LRDMA copy.
+
+
+
+
+
+
+
+ GET_RTCE_BUFFER_SIZE
+
+
+ 0x03
+
+
+ Client Partition
+
+
+ 1
+
+
+ Obtains the recommended size for the TCE mapped buffer to be
+ used for TPM command/responses.
+
+
+
+
+
+
+
+ PREPARE_TO_SUSPEND
+
+
+ 0x04
+
+
+ Client Partition
+
+
+ 1
+
+
+ Informs the VTPM to perform pre-suspension activities.
+
+
+
+
+
+
+
+ REQUEST_NO_RAS_COMPONENTS
+
+
+ 0x05
+
+
+ Client Partition
+
+
+ 1
+
+
+ Obtain the number of components within the VTPM that have RAS
+ capabilities.
+
+
+
+
+
+
+
+ REQUEST_RAS_COMPONENTS
+
+
+ 0x06
+
+
+ Client Partition
+
+
+ 1
+
+
+ Obtain information about the components which have RAS
+ capabilities.
+
+
+
+
+
+
+
+ RAS_CONTROL
+
+
+ 0x07
+
+
+ Client Partition
+
+
+ 3
+
+
+ Modify RAS capabilities of a component.
+
+
+
+
+
+
+
+ COLLECT_TRACE
+
+
+ 0x08
+
+
+ Client Partition
+
+
+ 4
+
+
+ Collect RAS tracing data.
+
+
+
+
+
+
+
+ REQUEST_DUMP_SIZE
+
+
+ 0x09
+
+
+ Client Partition
+
+
+ 1
+
+
+ Request the size for of the dump.
+
+
+
+
+
+
+
+ REQUEST_DUMP
+
+
+ 0x0A
+
+
+ Client Partition
+
+
+ 4
+
+
+ Request the dump.
+
+
+
+
+
+
+
+ VTPM_IN_FAIL_STATE
+
+
+ 0xFE
+
+
+ Client Partition
+
+
+ 1
+
+
+ A critical error has occurred and the VTPM cannot operate.
+
+
+
+
+
+
+
+ VTPM_ERROR
+
+
+ 0xFF
+
+
+ Client Partition
+
+
+ 2
+
+
+ An error occurred processing the last command. The VTPM is
+ still operational.
+
+
+
+
+
+
+
+
+
+
+ VTPM Message Format 1
+
+
+
+
+
+
+
+
+
+
+
+
+ Byte
+ 0
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+
+
+
+
+
+ Word 0
+
+
+ 0x80
+
+
+ Message Type
+
+
+ Length
+
+
+ Data
+
+
+
+
+ Word 1
+
+
+ Reserved
+
+
+
+
+
+
+
+ VTPM Message Format 2 (VTPM Error)
+
+
+
+
+
+
+
+
+
+
+
+
+ Byte
+ 0
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+
+
+
+
+
+ Word 0
+
+
+ 0x80
+
+
+ 0xFF
+
+
+ Reserved
+
+
+ VTPM Error
+
+
+
+
+ Word 1
+
+
+ Firmware Error Detail
+
+
+
+
+
+
+
+ VTPM Message Format 3 (RAS Control)
+
+
+
+
+
+
+
+
+
+
+
+
+ Byte
+ 0
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+
+
+
+
+
+ Word 0
+
+
+ 0x80
+
+
+ Message Type (0x07 or 0x87)
+
+
+ Correlator
+
+
+ Level
+
+
+ Operation
+
+
+ Trace Buffer Size
+
+
+
+
+ Word 1
+
+
+ Reserved
+
+
+
+
+
+
+
+ VTPM Message Format 4 (Collect Trace and Request Dump)
+
+
+
+
+
+
+
+
+
+
+
+
+ Byte
+ 0
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+
+
+
+
+
+ Word 0
+
+
+ 0x80
+
+
+ Message Type
+
+
+ Correlator
+
+
+ Reserved
+
+
+ IOBA
+
+
+
+
+ Word 1
+
+
+ Buffer Length
+
+
+ Reserved
+
+
+
+
+
+
+
+
+
+ Typical VTPM Flows
+
+
+ Boot Flow
+
+ This section gives an overview of the typical VTPM startup sequence from
+ the perspective of the client partition. This boot flow does not describe a
+ trusted boot, trusted boot is out of the scope of this document.
+
+
+
+ The client operating system discovers a VTPM node in the device tree.
+
+
+
+ The operating system instantiates the VTPM device driver, allocates
+ a buffer for the VTPM CRQ which then TCE-mapped using the VTPM’s TCE table.
+ Since the VTPM protocol is a command/response protocol, the VTPM device
+ driver must allocate a CRQ buffer big enough to handle a response for every
+ command it wishes to have outstanding concurrently with the VTPM with an
+ allowance for unsolicited CRQ transport events.
+
+
+
+ The VTPM device driver can now call H_REG_CRQ to register the CRQ buffer.
+ The call must specify the unit address and IOBA of the CRQ page(s),
+ and waits for either H_Success or an INITIALIZATION message as defined in
+ .
+
+
+
+ The VTPM device driver sends either an INITIALIZATION_COMPLETE or an
+ INITIALIZATION message to firmware using H_SEND_CRQ, as defined in
+ .
+
+
+
+ Once the INITIALIZATION and INITIALIZATION_COMPLETE messages have
+ been exchanged, the VTPM device driver sends a GET_VERSION message using
+ H_SEND_CRQ.
+
+
+
+ The VTPM responds with a GET_VERSION_RSP message specifying the VTPM
+ version. The version number allows the client to look-up and determine
+ what the valid CRQ messages are and what the TPM specification is enabled.
+
+
+
+ Providing that the client supports the VTPM version a GET_RTCE_BUFFER_SIZE
+ message must be sent to the VTPM.
+
+
+
+ The VTPM responds with a GET_RTCE_BUFFER_SIZE_RSP message containing
+ the number of bytes that must be TCE mapped for TPM commands and responses.
+ The value is be rounded up to a 4K page boundary.
+
+
+
+ The client now TCE maps the correct number of pages and can send TPM commands to the VTPM.
+
+
+
+
+
+
+
+ VTPM Message Types
+
+ All VTPM messages are sent using H_SEND_CRQ.
+
+
+ Get Version
+
+ The client can use the GET_VERSION message as defined in
+
+ to request a version number for the VTPM. The version number must be used
+ to determine what messages are available and what TPM specification is
+ supported. This message is only valid from client to VTPM.
+
+
+ Get Version Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x01
+
+
+
+
+ Length
+
+
+ Unused
+
+
+
+
+ Data
+
+
+ Unused
+
+
+
+
+
+
+
+
+ Get Version Response
+
+ This response message as defined in
+
+ contains a version number which can then be used by the client to determine
+ what CRQ messages are available and what TPM specification is supported.
+
+ defines the version numbers and what that mean. This message is only valid
+ from VTPM to client.
+
+
+ Get Version Response Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x81
+
+
+
+
+ Length
+
+
+ 0
+
+
+
+
+ Data
+
+
+ Version Number
+
+
+
+
+
+
+
+
+ VTPM Version Number Values
+
+
+
+
+
+
+
+ Value
+
+
+
+
+ Meaning
+
+
+
+
+
+
+
+ 1
+
+
+ TPM 1.2 and the CRQ protocol as defined in this document.
+
+
+
+
+ 2
+
+
+ TPM 2.0 and the CRQ protocol as defined in this document.
+
+
+
+
+
+
+
+
+ TPM Command
+
+ The client uses the message as defined in
+
+ to indicate to the VTPM that a TPM command has been written to a TCE mapped
+ buffer and is ready for processing. On successful completion of the processing
+ the VTPM writes to the same buffer with a TPM response. This message is only
+ valid from client to VTPM.
+
+
+ TPM Command Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x02
+
+
+
+
+ Length
+
+
+ The size in bytes of the TPM command for the copy-in.
+
+
+
+
+ Data
+
+
+ IOBA corresponding to the TCE mapped buffer storing the TPM command.
+
+
+
+
+
+
+
+
+ TPM Response
+
+ The VTPM when responding to a TPM command uses the message as defined in
+
+ to indicate that a TPM response has been transferred to the clients TCE
+ mapped buffer. This message is only valid from the VTPM to client.
+
+
+ TPM Response Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x82
+
+
+
+
+ Length
+
+
+ The size in bytes of the TPM response copied out.
+
+
+
+
+ Data
+
+
+ The IOBA corresponding to the TCE mapped buffer storing the
+ TPM command as set by the TPM command message.
+
+
+
+
+
+
+
+
+ Get RTCE Buffer Size
+
+ The client uses the message as defined in
+
+ to discover the size of the TCE mapped buffer it needs to allocate for
+ stable TPM communications. This value represents the maximum size the VTPM
+ can copy-in and out. This message is only valid from the client to VTPM.
+
+
+ Get RTCE Buffer Size
+
+
+
+
+
+
+ Message Type
+
+
+ 0x03
+
+
+
+
+ Length
+
+
+ Unused
+
+
+
+
+ Data
+
+
+ Unused
+
+
+
+
+
+
+
+
+ Get RTCE Buffer Size Response
+
+ The message as defined in
+
+ is sent by the VTPM and contains the size in bytes that the client must
+ use when allocating a TCE mapped buffer for VTPM communication. Failure
+ to allocate a buffer of this size may lead to future TPM response transfers
+ failing. This message is only valid from VTPM to client.
+
+
+ Get RTCE Buffer Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x83
+
+
+
+
+ Length
+
+
+ The size in bytes to be used for the TCE mapped buffer.
+
+
+
+
+ Data
+
+
+ 0
+
+
+
+
+
+
+
+
+ Prepare to Suspend
+
+ The client can use the message as defined in
+
+ to instruct the VTPM to prepare for migration or hibernation. The command
+ instructs the VTPM to suspend operations so that firmware can safely migrate
+ or hibernate the VTPM. Note that after sending this message the VTPM no
+ longer processes messages until the VTPM is rebooted. This message is
+ only valid from client to VTPM.
+
+
+ Prepare to Suspend Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x04
+
+
+
+
+ Length
+
+
+ Unused
+
+
+
+
+ Data
+
+
+ Unused
+
+
+
+
+
+
+
+
+ Prepare to Suspend Response
+
+ The VTPM sends the message as defined in
+
+ in response to a “Prepare to suspend” message after completing required
+ suspend operations. The client can assume that the VTPM is now safe to be
+ migrated or hibernated. This message is only valid from VTPM to client.
+
+
+ Prepare to Suspend Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x84
+
+
+
+
+ Length
+
+
+ 0
+
+
+
+
+ Data
+
+
+ 0
+
+
+
+
+
+
+
+
+ Request Number of RAS Components
+
+ The client sends the message as defined in
+
+ to retrieve a count of how many components have RAS capabilities. This
+ message is only valid from client to VTPM.
+
+
+ Request Number of RAS Components Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x05
+
+
+
+
+ Length
+
+
+ Unused
+
+
+
+
+ Data
+
+
+ Unused
+
+
+
+
+
+
+
+
+ Request Number of RAS Components Response
+
+ The VTPM sends the message as defined in
+
+ to inform the client how many components have controllable RAS capabilities.
+ The value must be used in sizing buffers for further RAS messages. This
+ message is only valid from VTPM to client.
+
+
+ Request Number of RAS Components Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x85
+
+
+
+
+ Length
+
+
+ 0
+
+
+
+
+ Data
+
+
+ The number of VTPM components with controllable RAS capabilities.
+
+
+
+
+
+
+
+
+ Request RAS Components
+
+ The client can use the message as defined in
+
+ to retrieve a list of RAS component structures detailing each RAS component.
+ The value returned from REQUEST_NO_OF_RAS_COMPONENTS must be used when
+ sizing the transfer buffer. Each entry returned by the
+ VTPM is a structure as defined in
+ .
+ This message is only valid from client to VTPM.
+
+
+ Request RAS Components Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x06
+
+
+
+
+ Length
+
+
+ Maximum number of bytes to be transferred.
+
+
+
+
+ Data
+
+
+ The IOBA associated with a buffer to be used for the LRDMA copy-out.
+
+
+
+
+
+
+
+ RAS Component Structure
+
+
+
+
+
+
+
+ Field Name
+ Byte Offset
+ Length
+ Definition
+
+
+
+
+
+ Component Name
+
+
+ 0
+
+
+ 48
+
+
+ This field contains an ASCII string containing a readable name
+ of the component.
+
+
+
+
+ Trace Buffer Size
+
+
+ 48
+
+
+ 4
+
+
+ This field contains the size of the trace buffer in bytes.
+
+
+
+
+ Correlator
+
+
+ 52
+
+
+ 1
+
+
+ This field contains a valued to be used on a collect trace
+ message.
+
+
+
+
+ Trace Level
+
+
+ 53
+
+
+ 1
+
+
+ This field shows the current trace level.
+
+
+
+
+ Parent Correlator
+
+
+ 54
+
+
+ 1
+
+
+ This field contains the correlator of the parent component.
+ 0xFF indicates there is no parent.
+
+
+
+
+ Error Checking
+
+
+ 55
+
+
+ 1
+
+
+ This field contains the error checking level for this component.
+ It contains a value from 0-9, where 0 means no extra error checking,
+ and 9 means the highest level of consistency checking. A value of
+ 0xFF indicates that the component does not support changing the
+ level of error checking.
+
+
+
+
+ Trace State
+
+
+ 56
+
+
+ 1
+
+
+ If this field is 0 then the component's tracing is turned off.
+ A value of 1 indicates that tracing is enabled.
+
+
+
+
+ Reserved
+
+
+ 57
+
+
+ 7
+
+
+ Reserved and set to 0.
+
+
+
+
+ Description
+
+
+ 64
+
+
+ 192
+
+
+ An ASCII string containing a readable description of the component.
+
+
+
+
+
+
+
+
+ Request RAS Components Response
+
+ The VTPM sends the message as defined in
+
+ in response to a REQUEST_RAS_COMPONENTS message. This message indicates that
+ the VTPM has copied data to the TCE mapped buffer specified by the client,
+ the number of bytes copied is in the length field. This message is only
+ valid from VTPM to client.
+
+
+ Request RAS Components Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x86
+
+
+
+
+ Length
+
+
+ Actual number of bytes copied (up to the value given by the client).
+
+
+
+
+ Data
+
+
+ The IOBA associated with the buffer used in the LRDMA copy-out.
+
+
+
+
+
+
+
+
+ RAS Control
+
+ The client sends the message as defined in
+
+ to retrieve a count of how many components have RAS capabilities. This
+ message is only valid from client to VTPM.
+
+
+ RAS Control Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x07
+
+
+
+
+ Correlator
+
+
+ This field is set to a correlator as found by a
+ “Request RAS Components” message.
+ This value selects the component to control.
+
+
+
+
+ Level
+
+
+ This field must be a value between 0 and 9, where a larger
+ number indicates a higher detail of tracing or error checking.
+
+
+
+
+ Operation
+
+
+ This field controls what action the RAS control message performs.
+ 1: Use the level field to modify current trace level of the specified component.
+ 2: Use the level field to modify the current error checking level of the specified component.
+ 3: Suspend the tracing for the specified component that was previously on.
+ 4: Resume the tracing for the specified component that was previously suspended.
+ 5: Turn tracing on for the specified component.
+ 6: Turn tracing off for the specified component.
+ 7: Change the size trace buffer for the specified component.
+
+
+
+
+ Trace Buffer Size
+
+
+ If the operation field is 7 then this field contains the
+ new size for the trace buffer, otherwise the current buffer
+ size is returned. All values are number of bytes.
+
+
+
+
+
+
+
+
+ RAS Control Response
+
+ The VTPM sends the message as defined in
+
+ if a request to change RAS characteristics was successful. This
+ message is only valid from VTPM to client.
+
+
+ RAS Control Response Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x87
+
+
+
+
+ Correlator
+
+
+ This field is set to the value the client passed.
+
+
+
+
+ Level
+
+
+ This field is set to the value the client passed.
+
+
+
+
+ Operation
+
+
+ This field is set to the value the client passed.
+
+
+
+
+ Trace Buffer Size
+
+
+ This field is always set to the current size in bytes of the
+ trace buffer for the correlator.
+
+
+
+
+
+
+
+
+ Collect Trace
+
+ The client uses the message as defined in
+
+ to retrieve tracing information from the VTPM. The amount of data available
+ for collection is discovered by issuing a RAS_CONTROL message, the Trace
+ Buffer Size field indicates the size. The trace data copied
+ is an array of structures as defined in
+ .
+ This message is only valid from client to VTPM.
+
+
+ Collect Trace Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x08
+
+
+
+
+ Correlator
+
+
+ This field must be set to a correlator as found by a
+ “Request RAS Components” message. This value selects the
+ component to control.
+
+
+
+
+ IOBA
+
+
+ The TCE value associated with a buffer to receive trace data.
+
+
+
+
+ Trace Buffer Size
+
+
+ The maximum amount of data in bytes that the client requires to be copied.
+
+
+
+
+
+
+
+
+ Firmware Trace Data Entry Structure
+
+
+
+
+
+
+
+
+ Field Name
+
+
+
+
+ Byte Offset
+
+
+
+
+ Length
+
+
+
+
+
+
+
+ Trace ID
+
+
+ 0
+
+
+ 4
+
+
+
+
+ Numberf Valid Trace Data
+
+
+ 4
+
+
+ 1
+
+
+
+
+ Reserved
+
+
+ 5
+
+
+ 3
+
+
+
+
+ Reserved
+
+
+ 8
+
+
+ 8
+
+
+
+
+ Time Base
+
+
+ 16
+
+
+ 8
+
+
+
+
+ Trace Data 1
+
+
+ 24
+
+
+ 8
+
+
+
+
+ Trace Data 2
+
+
+ 32
+
+
+ 8
+
+
+
+
+ Trace Data 3
+
+
+ 40
+
+
+ 8
+
+
+
+
+ Trace Data 4
+
+
+ 48
+
+
+ 8
+
+
+
+
+ Trace Data 5
+
+
+ 56
+
+
+ 8
+
+
+
+
+
+
+
+
+ Collect Trace Response
+
+ This response as defined in
+
+ indicates that requested trace data was successfully copied to the IOBA
+ supplied by the client. This message is only valid from VTPM to client.
+
+
+ Collect Trace Response Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x88
+
+
+
+
+ Correlator
+
+
+ Same value sent by client.
+
+
+
+
+ IOBA
+
+
+ The IOBA value used in the copy (as set by client).
+
+
+
+
+ Trace Buffer Size
+
+
+ The actual number of bytes copied.
+
+
+
+
+
+
+
+
+ Request Dump Size
+
+ The client uses the message as defined in
+
+ to retrieve the size in bytes required to store a dump.
+ This message is only valid from client to VTPM.
+
+
+ Request Dump Size
+
+
+
+
+
+
+ Message Type
+
+
+ 0x09
+
+
+
+
+ Length
+
+
+ 0
+
+
+
+
+ Data
+
+
+ 0
+
+
+
+
+
+
+
+
+ Request Dump Size Response
+
+ The VTPM returns the message as define in
+
+ when the client has request the dump size, to allow for greater then
+ values larger than 216 to be returned, the data
+ field is used. This message is only valid from VTPM to client.
+
+
+ Request Dump Size Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x89
+
+
+
+
+ Length
+
+
+ 0
+
+
+
+
+ Data
+
+
+ The number of bytes required to store a dump.
+
+
+
+
+
+
+
+
+ Request Dump
+
+ The client uses the message as defined in
+
+ to retrieve a dump. The client should first ensure that enough space is
+ available by using the “Request Dump Size” message. This message is
+ only valid from client to VTPM.
+
+
+ Request Dump Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0x0A
+
+
+
+
+ Correlator
+
+
+ 0
+
+
+
+
+ IOBA
+
+
+ The TCE value associated with a buffer to receive dump data.
+
+
+
+
+ Dump Data Size
+
+
+ The maximum amount of data in bytes that the client requires
+ to be copied.
+
+
+
+
+
+
+
+
+ Request Dump Response
+
+ The VTPM returns the message as define in
+
+ when a dump has been copied to the client's buffer. This message is only
+ valid from VTPM to client.
+
+
+ Request Dump Response
+
+
+
+
+
+
+ Message Type
+
+
+ 0x8A
+
+
+
+
+ Correlator
+
+
+ 0
+
+
+
+
+ IOBA
+
+
+ The IOBA value used in the copy (as set by client).
+
+
+
+
+ Dump Data Size
+
+
+ The actual number of bytes copied.
+
+
+
+
+
+
+
+
+ VTPM in Fail State
+
+ The VTPM returns the message as defined in
+
+ when the VTPM has entered the fail state. This FAIL_STATE message is sent
+ in response to any incoming message (valid or invalid) except for
+ RAS messages. Whilst in the fail state the VTPM makes every effort to
+ service RAS messages. This message is only valid from VTPM to client.
+
+
+ VTPM in Fail State Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0xFE
+
+
+
+
+ Length
+
+
+ Not used, VTPM sets to 0
+
+
+
+
+ Data
+
+
+ The EC value as defined in
+ .
+
+
+
+
+
+
+
+
+ VTPM Error
+
+ The VTPM returns the message as defined in
+
+ when one of the conditions in
+
+ is encountered. This message is only valid from VTPM to client.
+
+
+ VTPM Error Message
+
+
+
+
+
+
+ Message Type
+
+
+ 0xFF
+
+
+
+
+ VTPM Error
+
+
+
+
+
+
+
+ Firmware Error Detail
+
+
+ Firmware may set this field to a more detailed error code.
+ A value of 0 indicates no detailed error.
+
+
+
+
+
+
+
+ VTPM Error Codes
+
+
+
+
+
+
+
+ Value of "data" field
+
+
+
+
+ Meaning
+
+
+
+
+
+
+
+ 1
+
+
+ Message type field set to a unknown/illegal value. Client must
+ check the VTPM version number with “Get Version”
+
+
+
+
+ 2
+
+
+ Message Type is “TPM command” and length exceeded the maximum
+ transfer size. Client must not exceed the value returned by
+ GET_RTCE_BUFFER_SIZE.
+
+
+
+
+ 3
+
+
+ After receiving a “TPM Command” message the LRDMA copy-in failed.
+
+
+
+
+ 4
+
+
+ After processing a “TPM Command” message the LRDMA copy-out failed.
+
+
+
+
+ 5
+
+
+ An unexpected error occurred during TPM command processing.
+
+
+
+
+ 6
+
+
+ After receiving a “Request Number Of RAS Components” message,
+ retrieving the number of RAS components failed.
+
+
+
+
+ 7
+
+
+ After receiving a “Request RAS Components” message the
+ LRDMA copy-out failed.
+
+
+
+
+ 8
+
+
+ After receiving a “Request RAS Components” message obtaining
+ a list of correlators failed.
+
+
+
+
+ 9
+
+
+ After receiving a “RAS Control” message the operation field is
+ 1 or 2 and level is not valid.
+
+
+
+
+ 10
+
+
+ After receiving a “RAS Control” message the operation is not valid.
+
+
+
+
+ 11
+
+
+ After receiving a “RAS Control” message the control modification failed.
+
+
+
+
+ 12
+
+
+ After receiving a “Collect Trace” message the LRDMA copy-out failed.
+
+
+
+
+ 13
+
+
+ After receiving a “Request Dump” message the LRDMA copy-out failed.
+
+
+
+
+
+
+
+
+
+ Fail State
+
+ The VTPM has a number of detectable Errors Conditions (EC) which that
+ prevent the VTPM from operating. On detecting an EC the VTPM enters the
+ Fail State to which it does not process some commands. For example TPM c
+ ommands cannot be processed and the VTPM responds with the message as defined in
+ . Note that during the Fail State the
+ VTPM makes a best effort attempt to accept and respond to RAS messages.
+
+ The Fail State can only be cleared by taking appropriate action to clear
+ the underlying problem and restarting the client partition.
+
+
+
+ VTPM EC Definitions
+
+
+
+
+
+
+
+ EC Number
+
+
+
+
+ Meaning
+
+
+
+
+
+
+
+ 1
+
+
+ VTPM non-volatile saved data was loaded and the integrity
+ The Fail State can only be cleared by taking appropriate action to clear the underlying problem and restarting the client partition.checking failed.
+
+
+
+
+ 2
+
+
+ VTPM volatile and non-volatile saved data was found with an
+ illegal/incompatible version number.
+
+
+
+
+ 3
+
+
+ VTPM volatile and non-volatile saved data was found and the
+ integrity check failed.
+
+
+
+
+ 4
+
+
+ VTPM volatile and non-volatile saved data was with an illegal state.
+
+
+
+
+
+
+
+
+ Hypercall Error Handling
+
+ The following error handling recommendations must be considered by client software.
+
+
+ VTPM Error Message Received
+
+ If a VTPM Error message is sent indicating that LRDMA copy-out of a
+ TPM Response had failed the VTPM state is updated irrespective of the copy-out failure.
+
+
+
+ H_SEND_CRQ Error
+
+ If the client issues H_SEND_CRQ receives either H_Dropped or H_Closed the
+ following recommendation apply.
+
+
+ H_Dropped
+
+ The client has filled the CRQ buffer, it is recommended that the
+ client yields and waits for the VTPM to respond to a message already in
+ the CRQ buffer freeing space for new messages.
+
+
+
+
+ H_Closed
+
+ The VTPM has either fatally terminated or firmware is reloading the VTPM.
+ The CRQ buffer should be checked for Transport Events then
+ appropriate action taken as defined in
+ .
+
+
+
+
+ CRQ Transport Events
+
+ If the client receives either a “Partner Partition De-Registered” or
+ “Partner Partition Failed” transport event the following recommendations apply.
+
+
+ Partner Partition De-Registered
+
+ The VTPM is in the process of being reloaded by firmware and has
+ de-registered the CRQ. The client must wait for the CRQ INTIALIZATION
+ message and respond as defined in
+ ,
+ The client must resubmit any messages to which it has not had a response.
+
+
+
+ Partner Partition Failed
+
+ The VTPM has terminated fatally, the client must be rebooted to
+ reinstate a trusted VTPM state.
+
+
+
+
+