From 0b4648a5dbca426db367ccd5158bb658245e673e Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Tue, 14 Apr 2020 13:33:41 -0500 Subject: [PATCH] VTPM (version 1 and 2) Signed-off-by: Jeff Scheel --- Virtualization/bk_main.xml | 1 + Virtualization/ch_virtual_io.xml | 357 +++++ Virtualization/ch_virtual_tpm.xml | 2372 +++++++++++++++++++++++++++++ 3 files changed, 2730 insertions(+) create mode 100644 Virtualization/ch_virtual_tpm.xml 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. +
+
+
+
+