|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
<!--
|
|
|
Copyright (c) 2016, 2020 OpenPOWER Foundation
|
|
|
|
|
|
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.
|
|
|
|
|
|
-->
|
|
|
<appendix xmlns="http://docbook.org/ns/docbook"
|
|
|
xmlns:xl="http://www.w3.org/1999/xlink"
|
|
|
version="5.0"
|
|
|
xml:lang="en"
|
|
|
xml:id="ch_virtual_trusted_platform_module">
|
|
|
<title>Virtual Trusted Platform Module (VTPM)</title>
|
|
|
|
|
|
<section>
|
|
|
<title>A protocol for VTPM communications</title>
|
|
|
<para>The protocol defined in this appendix is to be used with the VTPM as defined in
|
|
|
<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>
|
|
|
</appendix>
|