systemsoftware
/
Linux-Architecture-Reference
35
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
papr_2.9+
papr_2.7
lopar-2.9
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '9bd105105e'
${ noResults }
Linux-Architecture-Reference/LoPAR/app_virtual_tpm.xml

2376 lines
85 KiB
XML
Raw Normal View History Unescape Escape

VTPM (version 1 and 2) Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
<?xml version="1.0" encoding="UTF-8"?>
<!--
File cleanup. Table cleanup. Minor edits. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
Copyright (c) 2016, 2020 OpenPOWER Foundation
VTPM (version 1 and 2) Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
Collapse 5 subdocs back into a single document. Clean build. Tag work needed. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
<appendix xmlns="http://docbook.org/ns/docbook"
File cleanup. Table cleanup. Minor edits. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="ch_virtual_trusted_platform_module">
VTPM (version 1 and 2) Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
<title>Virtual Trusted Platform Module (VTPM)</title>
<section>
<title>A protocol for VTPM communications</title>
Collapse 5 subdocs back into a single document. Clean build. Tag work needed. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
<para>The protocol defined in this appendix is to be used with the VTPM as defined in
VTPM (version 1 and 2) Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
<xref linkend="sec_virtual_trusted_platform_module" />.
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.</para>
<para>This protocol is designed to fulfil the following requirements:</para>
<orderedlist>
<listitem>
<para>Extensible protocol for future functional additions.</para>
</listitem>
<listitem>
<para>Allow client partition to perform RAS operations.</para>
</listitem>
</orderedlist>
<section>
<title>Protocol Overview</title>
<para>The protocol uses both the CRQ facility and Logical Remote DMA (LRDMA) as defined in
<xref linkend="dbdoclet.50569348_71217"/>
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.</para>
<para>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
<xref linkend="table_vtpm_message_types" />. The four message formats used by
the VTPM protocol are defined in the following tables:</para>
<itemizedlist>
<listitem>
<para><xref linkend="table_vtpm_message_format_1" /></para>
</listitem>
<listitem>
<para><xref linkend="table_vtpm_message_format_2" /></para>
</listitem>
<listitem>
<para><xref linkend="table_vtpm_message_format_3" /></para>
</listitem>
<listitem>
<para><xref linkend="table_vtpm_message_format_4" /></para>
</listitem>
</itemizedlist>
<para>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.</para>
<para>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
<xref linkend="dbdoclet.50569348_48491" />.</para>
<para>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
<xref linkend="sec_vtpm_fail_state" />.</para>
<table frame="all" pgwide="1" xml:id="table_vtpm_message_types">
<title>VTPM Message Types</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="7*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="8*" align="center" />
<colspec colname="c5" colwidth="30*" />
<colspec colname="c6" colwidth="20*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Message Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Sent By</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">CRQ Format Type</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Location</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>GET_VERSION</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Obtains the version of the VTPM.</para>
</entry>
<entry>
<para><xref linkend="sec_get_version" /></para>
</entry>
</row>
<row>
<entry>
<para>TPM_COMMAND</para>
</entry>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Informs the VTPM that a TPM command is ready for LRDMA copy.</para>
</entry>
<entry>
<para><xref linkend="sec_tpm_command" /></para>
</entry>
</row>
<row>
<entry>
<para>GET_RTCE_BUFFER_SIZE</para>
</entry>
<entry>
<para>0x03</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Obtains the recommended size for the TCE mapped buffer to be
used for TPM command/responses.</para>
</entry>
<entry>
<para><xref linkend="sec_get_rtce_buffer_size" /></para>
</entry>
</row>
<row>
<entry>
<para>PREPARE_TO_SUSPEND</para>
</entry>
<entry>
<para>0x04</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Informs the VTPM to perform pre-suspension activities.</para>
</entry>
<entry>
<para><xref linkend="sec_prepare_to_suspend" /></para>
</entry>
</row>
<row>
<entry>
<para>REQUEST_NO_RAS_<?linebreak?>COMPONENTS</para>
</entry>
<entry>
<para>0x05</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Obtain the number of components within the VTPM that have RAS
capabilities.</para>
</entry>
<entry>
<para><xref linkend="sec_request_no_ras_components" /></para>
</entry>
</row>
<row>
<entry>
<para>REQUEST_RAS_<?linebreak?>COMPONENTS</para>
</entry>
<entry>
<para>0x06</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Obtain information about the components which have RAS
capabilities.</para>
</entry>
<entry>
<para><xref linkend="sec_request_ras_components" /></para>
</entry>
</row>
<row>
<entry>
<para>RAS_CONTROL</para>
</entry>
<entry>
<para>0x07</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>Modify RAS capabilities of a component.</para>
</entry>
<entry>
<para><xref linkend="sec_ras_control" /></para>
</entry>
</row>
<row>
<entry>
<para>COLLECT_TRACE</para>
</entry>
<entry>
<para>0x08</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>Collect RAS tracing data.</para>
</entry>
<entry>
<para><xref linkend="sec_collect_trace" /></para>
</entry>
</row>
<row>
<entry>
<para>REQUEST_DUMP_SIZE</para>
</entry>
<entry>
<para>0x09</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Request the size for of the dump.</para>
</entry>
<entry>
<para><xref linkend="sec_request_dump_size" /></para>
</entry>
</row>
<row>
<entry>
<para>REQUEST_DUMP</para>
</entry>
<entry>
<para>0x0A</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>Request the dump.</para>
</entry>
<entry>
<para><xref linkend="sec_request_dump" /></para>
</entry>
</row>
<row>
<entry>
<para>VTPM_IN_FAIL_STATE</para>
</entry>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>A critical error has occurred and the VTPM cannot operate.</para>
</entry>
<entry>
<para><xref linkend="sec_vtpm_in_fail_state" /></para>
</entry>
</row>
<row>
<entry>
<para>VTPM_ERROR</para>
</entry>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>Client Partition</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>An error occurred processing the last command. The VTPM is
still operational.</para>
</entry>
<entry>
<para><xref linkend="sec_vtpm_error" /></para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_message_format_1">
<title>VTPM Message Format 1</title>
<tgroup cols="9">
<colspec colname="c1" colwidth="11*" align="center" />
<colspec colname="c2" colwidth="11*" align="center" />
<colspec colname="c3" colwidth="11*" align="center" />
<colspec colname="c4" colwidth="11*" align="center" />
<colspec colname="c5" colwidth="11*" align="center" />
<colspec colname="c6" colwidth="11*" align="center" />
<colspec colname="c7" colwidth="11*" align="center" />
<colspec colname="c8" colwidth="11*" align="center" />
<colspec colname="c9" colwidth="11*" align="center" />
<thead valign="middle">
<row>
<entry><para><emphasis role="bold">Byte</emphasis></para></entry>
<entry><para><emphasis role="bold">0</emphasis></para></entry>
<entry><para><emphasis role="bold">1</emphasis></para></entry>
<entry><para><emphasis role="bold">2</emphasis></para></entry>
<entry><para><emphasis role="bold">3</emphasis></para></entry>
<entry><para><emphasis role="bold">4</emphasis></para></entry>
<entry><para><emphasis role="bold">5</emphasis></para></entry>
<entry><para><emphasis role="bold">6</emphasis></para></entry>
<entry><para><emphasis role="bold">7</emphasis></para></entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Word 0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Message Type</para>
</entry>
<entry namest="c4" nameend="c5" >
<para>Length</para>
</entry>
<entry namest="c6" nameend="c9" >
<para>Data</para>
</entry>
</row>
<row>
<entry>
<para>Word 1</para>
</entry>
<entry namest="c2" nameend="c9" >
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_message_format_2">
<title>VTPM Message Format 2 (VTPM Error)</title>
<tgroup cols="9">
<colspec colname="c1" colwidth="11*" align="center" />
<colspec colname="c2" colwidth="11*" align="center" />
<colspec colname="c3" colwidth="11*" align="center" />
<colspec colname="c4" colwidth="11*" align="center" />
<colspec colname="c5" colwidth="11*" align="center" />
<colspec colname="c6" colwidth="11*" align="center" />
<colspec colname="c7" colwidth="11*" align="center" />
<colspec colname="c8" colwidth="11*" align="center" />
<colspec colname="c9" colwidth="11*" align="center" />
<thead valign="middle">
<row>
<entry><para><emphasis role="bold">Byte</emphasis></para></entry>
<entry><para><emphasis role="bold">0</emphasis></para></entry>
<entry><para><emphasis role="bold">1</emphasis></para></entry>
<entry><para><emphasis role="bold">2</emphasis></para></entry>
<entry><para><emphasis role="bold">3</emphasis></para></entry>
<entry><para><emphasis role="bold">4</emphasis></para></entry>
<entry><para><emphasis role="bold">5</emphasis></para></entry>
<entry><para><emphasis role="bold">6</emphasis></para></entry>
<entry><para><emphasis role="bold">7</emphasis></para></entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Word 0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0xFF</para>
</entry>
<entry namest="c4" nameend="c5" >
<para>Reserved</para>
</entry>
<entry namest="c6" nameend="c9" >
<para>VTPM Error</para>
</entry>
</row>
<row>
<entry>
<para>Word 1</para>
</entry>
<entry namest="c2" nameend="c9" >
<para>Firmware Error Detail</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_message_format_3">
<title>VTPM Message Format 3 (RAS Control)</title>
<tgroup cols="9">
<colspec colname="c1" colwidth="11*" align="center" />
<colspec colname="c2" colwidth="11*" align="center" />
<colspec colname="c3" colwidth="11*" align="center" />
<colspec colname="c4" colwidth="11*" align="center" />
<colspec colname="c5" colwidth="11*" align="center" />
<colspec colname="c6" colwidth="11*" align="center" />
<colspec colname="c7" colwidth="11*" align="center" />
<colspec colname="c8" colwidth="11*" align="center" />
<colspec colname="c9" colwidth="11*" align="center" />
<thead valign="middle">
<row>
<entry><para><emphasis role="bold">Byte</emphasis></para></entry>
<entry><para><emphasis role="bold">0</emphasis></para></entry>
<entry><para><emphasis role="bold">1</emphasis></para></entry>
<entry><para><emphasis role="bold">2</emphasis></para></entry>
<entry><para><emphasis role="bold">3</emphasis></para></entry>
<entry><para><emphasis role="bold">4</emphasis></para></entry>
<entry><para><emphasis role="bold">5</emphasis></para></entry>
<entry><para><emphasis role="bold">6</emphasis></para></entry>
<entry><para><emphasis role="bold">7</emphasis></para></entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Word 0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Message Type (0x07 or 0x87)</para>
</entry>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>Level</para>
</entry>
<entry>
<para>Operation</para>
</entry>
<entry namest="c7" nameend="c9" >
<para>Trace Buffer Size</para>
</entry>
</row>
<row>
<entry>
<para>Word 1</para>
</entry>
<entry namest="c2" nameend="c9" >
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_message_format_4">
<title>VTPM Message Format 4 (Collect Trace and Request Dump)</title>
<tgroup cols="9">
<colspec colname="c1" colwidth="11*" align="center" />
<colspec colname="c2" colwidth="11*" align="center" />
<colspec colname="c3" colwidth="11*" align="center" />
<colspec colname="c4" colwidth="11*" align="center" />
<colspec colname="c5" colwidth="11*" align="center" />
<colspec colname="c6" colwidth="11*" align="center" />
<colspec colname="c7" colwidth="11*" align="center" />
<colspec colname="c8" colwidth="11*" align="center" />
<colspec colname="c9" colwidth="11*" align="center" />
<thead valign="middle">
<row>
<entry><para><emphasis role="bold">Byte</emphasis></para></entry>
<entry><para><emphasis role="bold">0</emphasis></para></entry>
<entry><para><emphasis role="bold">1</emphasis></para></entry>
<entry><para><emphasis role="bold">2</emphasis></para></entry>
<entry><para><emphasis role="bold">3</emphasis></para></entry>
<entry><para><emphasis role="bold">4</emphasis></para></entry>
<entry><para><emphasis role="bold">5</emphasis></para></entry>
<entry><para><emphasis role="bold">6</emphasis></para></entry>
<entry><para><emphasis role="bold">7</emphasis></para></entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Word 0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry namest="c6" nameend="c9" >
<para>IOBA</para>
</entry>
</row>
<row>
<entry>
<para>Word 1</para>
</entry>
<entry namest="c2" nameend="c5" >
<para>Buffer Length</para>
</entry>
<entry namest="c6" nameend="c9" >
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Typical VTPM Flows</title>
<section>
<title>Boot Flow</title>
<para>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.</para>
<orderedlist>
<listitem>
<para>The client operating system discovers a VTPM node in the device tree.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
<listitem>
<para>The VTPM device driver sends either an INITIALIZATION_COMPLETE or an
INITIALIZATION message to firmware using H_SEND_CRQ, as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
<listitem>
<para>Once the INITIALIZATION and INITIALIZATION_COMPLETE messages have
been exchanged, the VTPM device driver sends a GET_VERSION message using
H_SEND_CRQ.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Providing that the client supports the VTPM version a GET_RTCE_BUFFER_SIZE
message must be sent to the VTPM.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>The client now TCE maps the correct number of pages and can send TPM commands to the VTPM.</para>
</listitem>
</orderedlist>
</section>
</section>
<section xml:id="sec_vtpm_message_types">
<title>VTPM Message Types</title>
<para>All VTPM messages are sent using H_SEND_CRQ.</para>
<section xml:id="sec_get_version">
<title>Get Version</title>
<para>The client can use the GET_VERSION message as defined in
<xref linkend="table_get_version_message" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_get_version_message">
<title>Get Version Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x01</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_get_version_response">
<title>Get Version Response</title>
<para>This response message as defined in
<xref linkend="table_get_version_response_message" />
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.
<xref linkend="table_vtpm_version_number_values" />
defines the version numbers and what that mean. This message is only valid
from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_get_version_response_message">
<title>Get Version Response Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x81</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>Version Number</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_version_number_values">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>VTPM Version Number Values</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" align="center" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry >
<para>
<emphasis role="bold">Meaning</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>TPM 1.2 and the CRQ protocol as defined in this document.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>TPM 2.0 and the CRQ protocol as defined in this document.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_tpm_command">
<title>TPM Command</title>
<para>The client uses the message as defined in
<xref linkend="table_tpm_command_message" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_tpm_command_message">
<title>TPM Command Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>The size in bytes of the TPM command for the copy-in.</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>IOBA corresponding to the TCE mapped buffer storing the TPM command.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_tpm_response">
<title>TPM Response</title>
<para>The VTPM when responding to a TPM command uses the message as defined in
<xref linkend="table_tpm_response_message" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_tpm_response_message">
<title>TPM Response Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x82</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>The size in bytes of the TPM response copied out.</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The IOBA corresponding to the TCE mapped buffer storing the
TPM command as set by the TPM command message.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_get_rtce_buffer_size">
<title>Get RTCE Buffer Size</title>
<para>The client uses the message as defined in
<xref linkend="table_get_rtcs_buffer_size" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_get_rtcs_buffer_size">
<title>Get RTCE Buffer Size</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x03</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_get_rtce_buffer_size_response">
<title>Get RTCE Buffer Size Response</title>
<para>The message as defined in
<xref linkend="table_get_rtcs_buffer_response" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_get_rtcs_buffer_response">
<title>Get RTCE Buffer Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x83</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>The size in bytes to be used for the TCE mapped buffer.</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_prepare_to_suspend">
<title>Prepare to Suspend</title>
<para>The client can use the message as defined in
<xref linkend="table_prepare_to_suspend" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_prepare_to_suspend">
<title>Prepare to Suspend Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x04</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_prepare_to_suspend_response">
<title>Prepare to Suspend Response</title>
<para>The VTPM sends the message as defined in
<xref linkend="table_prepare_to_suspend_response" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_prepare_to_suspend_response">
<title>Prepare to Suspend Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x84</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_no_ras_components">
<title>Request Number of RAS Components</title>
<para>The client sends the message as defined in
<xref linkend="table_request_no_ras_components" />
to retrieve a count of how many components have RAS capabilities. This
message is only valid from client to VTPM.</para>
<table frame="all" pgwide="1" xml:id="table_request_no_ras_components">
<title>Request Number of RAS Components Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x05</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_no_ras_components_response">
<title>Request Number of RAS Components Response</title>
<para>The VTPM sends the message as defined in
<xref linkend="table_request_no_ras_components_response" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_request_no_ras_components_response">
<title>Request Number of RAS Components Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x85</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The number of VTPM components with controllable RAS capabilities.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_ras_components">
<title>Request RAS Components</title>
<para>The client can use the message as defined in
<xref linkend="table_request_ras_components_message" />
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
<xref linkend="table_ras_compnent_structure" />.
This message is only valid from client to VTPM.</para>
<table frame="all" pgwide="1" xml:id="table_request_ras_components_message">
<title>Request RAS Components Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x06</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Maximum number of bytes to be transferred.</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The IOBA associated with a buffer to be used for the LRDMA copy-out.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_ras_compnent_structure">
<title>RAS Component Structure</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="30*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="40*" />
<thead valign="middle">
<row>
<entry align="center"><para><emphasis role="bold">Field Name</emphasis></para></entry>
<entry ><para><emphasis role="bold">Byte Offset</emphasis></para></entry>
<entry><para><emphasis role="bold">Length</emphasis></para></entry>
<entry align="center"><para><emphasis role="bold">Definition</emphasis></para></entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Component Name</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>48</para>
</entry>
<entry>
<para>This field contains an ASCII string containing a readable name
of the component.</para>
</entry>
</row>
<row>
<entry>
<para>Trace Buffer Size</para>
</entry>
<entry>
<para>48</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>This field contains the size of the trace buffer in bytes.</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>52</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>This field contains a valued to be used on a collect trace
message.</para>
</entry>
</row>
<row>
<entry>
<para>Trace Level</para>
</entry>
<entry>
<para>53</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>This field shows the current trace level.</para>
</entry>
</row>
<row>
<entry>
<para>Parent Correlator</para>
</entry>
<entry>
<para>54</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>This field contains the correlator of the parent component.
0xFF indicates there is no parent.</para>
</entry>
</row>
<row>
<entry>
<para>Error Checking</para>
</entry>
<entry>
<para>55</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry>
<para>Trace State</para>
</entry>
<entry>
<para>56</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>If this field is 0 then the component's tracing is turned off.
A value of 1 indicates that tracing is enabled.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>57</para>
</entry>
<entry>
<para>7</para>
</entry>
<entry>
<para>Reserved and set to 0.</para>
</entry>
</row>
<row>
<entry>
<para>Description</para>
</entry>
<entry>
<para>64</para>
</entry>
<entry>
<para>192</para>
</entry>
<entry>
<para>An ASCII string containing a readable description of the component.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_ras_components_response">
<title>Request RAS Components Response</title>
<para>The VTPM sends the message as defined in
<xref linkend="table_request_ras_components_response" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_request_ras_components_response">
<title>Request RAS Components Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x86</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Actual number of bytes copied (up to the value given by the client).</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The IOBA associated with the buffer used in the LRDMA copy-out.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_ras_control">
<title>RAS Control</title>
<para>The client sends the message as defined in
<xref linkend="table_ras_control_message" />
to retrieve a count of how many components have RAS capabilities. This
message is only valid from client to VTPM.</para>
<table frame="all" pgwide="1" xml:id="table_ras_control_message">
<title>RAS Control Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x07</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>This field is set to a correlator as found by a
“Request RAS Components” message.
This value selects the component to control.</para>
</entry>
</row>
<row>
<entry>
<para>Level</para>
</entry>
<entry>
<para>This field must be a value between 0 and 9, where a larger
number indicates a higher detail of tracing or error checking.</para>
</entry>
</row>
<row>
<entry>
<para>Operation</para>
</entry>
<entry>
<para>This field controls what action the RAS control message performs.<?linebreak?>
1: Use the level field to modify current trace level of the specified component.<?linebreak?>
2: Use the level field to modify the current error checking level of the specified component.<?linebreak?>
3: Suspend the tracing for the specified component that was previously on.<?linebreak?>
4: Resume the tracing for the specified component that was previously suspended.<?linebreak?>
5: Turn tracing on for the specified component.<?linebreak?>
6: Turn tracing off for the specified component.<?linebreak?>
7: Change the size trace buffer for the specified component.</para>
</entry>
</row>
<row>
<entry>
<para>Trace Buffer Size</para>
</entry>
<entry>
<para>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.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_ras_control_response">
<title>RAS Control Response</title>
<para>The VTPM sends the message as defined in
<xref linkend="table_ras_control_response" />
if a request to change RAS characteristics was successful. This
message is only valid from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_ras_control_response">
<title>RAS Control Response Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x87</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>This field is set to the value the client passed.</para>
</entry>
</row>
<row>
<entry>
<para>Level</para>
</entry>
<entry>
<para>This field is set to the value the client passed.</para>
</entry>
</row>
<row>
<entry>
<para>Operation</para>
</entry>
<entry>
<para>This field is set to the value the client passed.</para>
</entry>
</row>
<row>
<entry>
<para>Trace Buffer Size</para>
</entry>
<entry>
<para>This field is always set to the current size in bytes of the
trace buffer for the correlator.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_collect_trace">
<title>Collect Trace</title>
<para>The client uses the message as defined in
<xref linkend="table_collect_trace_message" />
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
<xref linkend="table_firmware_trace_data_entry_structure" />.
This message is only valid from client to VTPM.</para>
<table frame="all" pgwide="1" xml:id="table_collect_trace_message">
<title>Collect Trace Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x08</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>This field must be set to a correlator as found by a
“Request RAS Components” message. This value selects the
component to control.</para>
</entry>
</row>
<row>
<entry>
<para>IOBA</para>
</entry>
<entry>
<para>The TCE value associated with a buffer to receive trace data.</para>
</entry>
</row>
<row>
<entry>
<para>Trace Buffer Size</para>
</entry>
<entry>
<para>The maximum amount of data in bytes that the client requires to be copied.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_firmware_trace_data_entry_structure">
<?dbhtml table-width="50%" ?><?dbfo table-width="50%" ?>
<title>Firmware Trace Data Entry Structure</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="40*" />
<colspec colname="c2" colwidth="30*" align="center" />
<colspec colname="c3" colwidth="30*" align="center" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry >
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry >
<para>
<emphasis role="bold">Length</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Trace ID</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>Numberf Valid Trace Data</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>5</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Time Base</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Trace Data 1</para>
</entry>
<entry>
<para>24</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Trace Data 2</para>
</entry>
<entry>
<para>32</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Trace Data 3</para>
</entry>
<entry>
<para>40</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Trace Data 4</para>
</entry>
<entry>
<para>48</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
<row>
<entry>
<para>Trace Data 5</para>
</entry>
<entry>
<para>56</para>
</entry>
<entry>
<para>8</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_collect_trace_response">
<title>Collect Trace Response</title>
<para>This response as defined in
<xref linkend="table_collect_trace_response_message" />
indicates that requested trace data was successfully copied to the IOBA
supplied by the client. This message is only valid from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_collect_trace_response_message">
<title>Collect Trace Response Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x88</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>Same value sent by client.</para>
</entry>
</row>
<row>
<entry>
<para>IOBA</para>
</entry>
<entry>
<para>The IOBA value used in the copy (as set by client).</para>
</entry>
</row>
<row>
<entry>
<para>Trace Buffer Size</para>
</entry>
<entry>
<para>The actual number of bytes copied.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_dump_size">
<title>Request Dump Size</title>
<para>The client uses the message as defined in
<xref linkend="table_request_dump_size" />
to retrieve the size in bytes required to store a dump.
This message is only valid from client to VTPM.</para>
<table frame="all" pgwide="1" xml:id="table_request_dump_size">
<title>Request Dump Size</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x09</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_dump_size_response">
<title>Request Dump Size Response</title>
<para>The VTPM returns the message as define in
<xref linkend="table_request_dump_size_response" />
when the client has request the dump size, to allow for greater then
values larger than 2<superscript>16</superscript> to be returned, the data
field is used. This message is only valid from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_request_dump_size_response">
<title>Request Dump Size Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x89</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The number of bytes required to store a dump.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_dump">
<title>Request Dump</title>
<para>The client uses the message as defined in
<xref linkend="table_request_dump_message" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_request_dump_message">
<title>Request Dump Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x0A</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>IOBA</para>
</entry>
<entry>
<para>The TCE value associated with a buffer to receive dump data.</para>
</entry>
</row>
<row>
<entry>
<para>Dump Data Size</para>
</entry>
<entry>
<para>The maximum amount of data in bytes that the client requires
to be copied.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_request_dump_response">
<title>Request Dump Response</title>
<para>The VTPM returns the message as define in
<xref linkend="table_request_dump_response" />
when a dump has been copied to the client's buffer. This message is only
valid from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_request_dump_response">
<title>Request Dump Response</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0x8A</para>
</entry>
</row>
<row>
<entry>
<para>Correlator</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>IOBA</para>
</entry>
<entry>
<para>The IOBA value used in the copy (as set by client).</para>
</entry>
</row>
<row>
<entry>
<para>Dump Data Size</para>
</entry>
<entry>
<para>The actual number of bytes copied.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vtpm_in_fail_state">
<title>VTPM in Fail State</title>
<para>The VTPM returns the message as defined in
<xref linkend="table_vtpm_in_fail_state_message" />
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.</para>
<table frame="all" pgwide="1" xml:id="table_vtpm_in_fail_state_message">
<title>VTPM in Fail State Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0xFE</para>
</entry>
</row>
<row>
<entry>
<para>Length</para>
</entry>
<entry>
<para>Not used, VTPM sets to 0</para>
</entry>
</row>
<row>
<entry>
<para>Data</para>
</entry>
<entry>
<para>The EC value as defined in
<xref linkend="table_vtpm_ec_definitions" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vtpm_error">
<title>VTPM Error</title>
<para>The VTPM returns the message as defined in
<xref linkend="table_vtpm_error_message" />
when one of the conditions in
<xref linkend="table_vtpm_error_codes" />
is encountered. This message is only valid from VTPM to client.</para>
<table frame="all" pgwide="1" xml:id="table_vtpm_error_message">
<title>VTPM Error Message</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="80*" />
<tbody valign="middle">
<row>
<entry>
<para>Message Type</para>
</entry>
<entry>
<para>0xFF</para>
</entry>
</row>
<row>
<entry>
<para>VTPM Error</para>
</entry>
<entry>
<para><xref linkend="table_vtpm_error_codes" /></para>
</entry>
</row>
<row>
<entry>
<para>Firmware Error Detail</para>
</entry>
<entry>
<para>Firmware may set this field to a more detailed error code.
A value of 0 indicates no detailed error.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vtpm_error_codes">
<title>VTPM Error Codes</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Value of "data" field</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Meaning</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Message type field set to a unknown/illegal value. Client must
check the VTPM version number with “Get Version”</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Message Type is “TPM command” and length exceeded the maximum
transfer size. Client must not exceed the value returned by
GET_RTCE_BUFFER_SIZE.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>After receiving a “TPM Command” message the LRDMA copy-in failed.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>After processing a “TPM Command” message the LRDMA copy-out failed.</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>An unexpected error occurred during TPM command processing.</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>After receiving a “Request Number Of RAS Components” message,
retrieving the number of RAS components failed.</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>After receiving a “Request RAS Components” message the
LRDMA copy-out failed.</para>
</entry>
</row>
<row>
<entry>
<para>8</para>
</entry>
<entry>
<para>After receiving a “Request RAS Components” message obtaining
a list of correlators failed.</para>
</entry>
</row>
<row>
<entry>
<para>9</para>
</entry>
<entry>
<para>After receiving a “RAS Control” message the operation field is
1 or 2 and level is not valid.</para>
</entry>
</row>
<row>
<entry>
<para>10</para>
</entry>
<entry>
<para>After receiving a “RAS Control” message the operation is not valid.</para>
</entry>
</row>
<row>
<entry>
<para>11</para>
</entry>
<entry>
<para>After receiving a “RAS Control” message the control modification failed.</para>
</entry>
</row>
<row>
<entry>
<para>12</para>
</entry>
<entry>
<para>After receiving a “Collect Trace” message the LRDMA copy-out failed.</para>
</entry>
</row>
<row>
<entry>
<para>13</para>
</entry>
<entry>
<para>After receiving a “Request Dump” message the LRDMA copy-out failed.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section xml:id="sec_vtpm_fail_state">
<title>Fail State</title>
<para>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
<xref linkend="sec_vtpm_in_fail_state" />. Note that during the Fail State the
VTPM makes a best effort attempt to accept and respond to RAS messages.</para>
<para>The Fail State can only be cleared by taking appropriate action to clear
the underlying problem and restarting the client partition.</para>
<table frame="all" pgwide="1" xml:id="table_vtpm_ec_definitions">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>VTPM EC Definitions</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">EC Number</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Meaning</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>VTPM volatile and non-volatile saved data was found with an
illegal/incompatible version number.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>VTPM volatile and non-volatile saved data was found and the
integrity check failed.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>VTPM volatile and non-volatile saved data was with an illegal state.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_hypercall_error_handling">
<title>Hypercall Error Handling</title>
<para>The following error handling recommendations must be considered by client software.</para>
<section>
<title>VTPM Error Message Received</title>
<para>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.</para>
</section>
<section>
<title>H_SEND_CRQ Error</title>
<para>If the client issues H_SEND_CRQ receives either H_Dropped or H_Closed the
following recommendation apply.</para>
<section>
<title>H_Dropped</title>
<para>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.
</para>
</section>
<section>
<title>H_Closed</title>
<para>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
<xref linkend="sec_crq_transport_events" />.</para>
</section>
</section>
<section xml:id="sec_crq_transport_events">
<title>CRQ Transport Events</title>
<para>If the client receives either a “Partner Partition De-Registered” or
“Partner Partition Failed” transport event the following recommendations apply.</para>
<section>
<title>Partner Partition De-Registered</title>
<para>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
<xref linkend="dbdoclet.50569348_48491" />,
The client must resubmit any messages to which it has not had a response.</para>
</section>
<section>
<title>Partner Partition Failed</title>
<para>The VTPM has terminated fatally, the client must be rebooted to
reinstate a trusted VTPM state.</para>
</section>
</section>
</section>
</section>
Collapse 5 subdocs back into a single document. Clean build. Tag work needed. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
5 years ago
</appendix>