The protocol defined in this appendix 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.

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 . 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. Byte 0 1 2 3 4 5 6 7 Word 0 0x80 Message Type Length Data Word 1 Reserved Byte 0 1 2 3 4 5 6 7 Word 0 0x80 0xFF Reserved VTPM Error Word 1 Firmware Error Detail 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 Byte 0 1 2 3 4 5 6 7 Word 0 0x80 Message Type Correlator Reserved IOBA Word 1 Buffer Length Reserved

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.

All VTPM messages are sent using H_SEND_CRQ.

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. Message Type 0x01 Length Unused Data Unused

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. Message Type 0x81 Length 0 Data Version Number 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.

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. 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.

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. 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.

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. Message Type 0x03 Length Unused Data Unused

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. Message Type 0x83 Length The size in bytes to be used for the TCE mapped buffer. Data 0

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. Message Type 0x04 Length Unused Data Unused

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. Message Type 0x84 Length 0 Data 0

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. Message Type 0x05 Length Unused Data Unused

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. Message Type 0x85 Length 0 Data The number of VTPM components with controllable RAS capabilities.

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. 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. 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.

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. 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.

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. 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.

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. 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.

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. 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. 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

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. 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.

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. Message Type 0x09 Length 0 Data 0

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. Message Type 0x89 Length 0 Data The number of bytes required to store a 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. 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.

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. 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.

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. Message Type 0xFE Length Not used, VTPM sets to 0 Data The EC value as defined in .

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. 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. 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.

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. 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.

The following error handling recommendations must be considered by client software.

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.

If the client issues H_SEND_CRQ receives either H_Dropped or H_Closed the following recommendation apply.

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.

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 .

If the client receives either a “Partner Partition De-Registered” or “Partner Partition Failed” transport event the following recommendations apply.

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.

The VTPM has terminated fatally, the client must be rebooted to reinstate a trusted VTPM state.