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.
Linux-Architecture-Reference/Virtualization/ch_vmc_comm.xml

1302 lines
49 KiB
XML

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title>A Protocol for VMC Communications</title>
<section>
<title>Overview</title>
<para>The Virtual Management Channel (VMC) is a logical device which
provides an interface between the hypervisor and a management partition.
This management partition is intended to provide an alternative to
HMC-based system management. In the management partition, a Logical
Partition Manager (LPM) application exists which enables a system
administrator to configure the system&#8217;s partitioning characteristics
via a command line interface or web browser. Support for conventional HMC
management of the system may still be provided on a system; however, when
an HMC is attached to the system, the VMC interface is disabled by the
hypervisor.</para>
<section>
<title>Logical Partition Manager</title>
<para>The LPM is a browser based LPAR configuration tool provided by the
management partition. System configuration, maintenance, and control
functions which traditionally require an HMC can be implemented in the
LPM using a combination of HMC to hypervisor interfaces and existing
operating system methods. This tool provides a subset of the functions
implemented by the HMC and enables basic partition configuration. The set
of HMC to hypervisor messages supported by the LPM component are passed
to the hypervisor over a VMC interface, which is defined below. The
actual content of these messages is defined in other documentation. In
order to remain consistent with this existing HMC documentation, this
chapter generally uses the HMC terminology to refer to these messages
and the LPM to hypervisor connections.</para>
</section>
<section>
<title>Virtual Management Channel (VMC)</title>
<para>A logical device, called the virtual management channel (VMC), is
defined for communicating between the LPM application and the hypervisor.
This device, similar to a VSCSI server device, is presented to a
designated management partition as a virtual device and is only presented
when the system is not HMC managed.</para>
<para>This communication device borrows aspects from both VSCSI and ILLAN
devices and is implemented using the CRQ and the RDMA interfaces. The
initialization process for CRQs is defined in
<xref linkend="dbdoclet.50569348_71217" />, and is not duplicated here. A
three way handshake is defined that must take place to establish that
both the hypervisor and management partition sides of the channel are
running prior to sending/receiving any of the protocol messages defined
in this chapter.</para>
<para>Transport Event CRQs are also defined in
<xref linkend="dbdoclet.50569348_71217" />, and are not duplicated here.
They define the CRQ messages that are sent when the hypervisor detects
one of the peer partitions has abnormally terminated, or one side has
called H_FREE_CRQ to close their CRQ.</para>
<para>Two new classes of CRQ messages are introduced for the VMC device.
VMC Administrative messages are used for each partition using the VMC to
communicate capabilities to their partner. HMC Interface messages are
used for the actual flow of HMC messages between the management partition
and the hypervisor. As most HMC messages far exceed the size of a CRQ
bugger, a virtual DMA (RMDA) of the HMC message data is done prior to
each HMC Interface CRQ message. Only the management partition drives RDMA
operations; hypervisor never directly causes the movement of message
data.</para>
</section>
</section>
<section>
<title>VMC CRQ Message Definition</title>
<para>For the VMC interface, all CRQ messages are defined to use the
following base format:</para>
<table frame="all" pgwide="1">
<title>CRQ Message Base Format</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>14 B</para>
</entry>
</row>
<row>
<entry>
<para>Header</para>
</entry>
<entry>
<para>Type</para>
</entry>
<entry>
<para>Data</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Two general message formats are defined: administrative and HMC
Interface. These are defined in the following sections.</para>
<section>
<title>Administrative Messages</title>
<para>The administrative message format is used to configure a VMC
between the hypervisor and the management partition. The two messages
defined for this format are described in the following
subsections.</para>
<section>
<title>VMC Capabilities</title>
<table frame="all" pgwide="1">
<title>VMC Capabilities Message</title>
<?dbhtml table-width="90%" ?><?dbfo table-width="90%" ?>
<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" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para># HMC&#8217;s</para>
</entry>
<entry>
<para>Pool Size</para>
</entry>
<entry>
<para>MTU</para>
</entry>
<entry>
<para>CRQ Size</para>
</entry>
<entry>
<para>Version (Major/Minor)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The capabilities message is an administrative message sent after
the CRQ initialization sequence of messages and is used to exchange VMC
capabilities between the management partition and the hypervisor. The
management partition must send this message and the hypervisor must
respond with a VMC Capabilities Response message before HMC interface
messages can begin. Any HMC interface messages received before the
exchange of capabilities has completed are dropped.</para>
<para>This message enables the management partition and the hypervisor to
trade the following interface parameters:</para>
<orderedlist>
<listitem>
<para># HMC&#8217;s. Maximum number of independent HMC connections
supported. Multiple connections would be required to support HMC pass
through mode.</para>
</listitem>
<listitem>
<para>Pool Size. Maximum number of buffers supported per HMC
connection.</para>
</listitem>
<listitem>
<para>MTU. Maximum message size supported (bytes).</para>
</listitem>
<listitem>
<para>CRQ Size. Number of entries available in the CRQ for the source
partition. The target partition must limit the number of outstanding
messages to one half or less.</para>
</listitem>
<listitem>
<para>Version. Indicates the code level of the management partition or
the hypervisor with the high-order byte indicating a major version and
the low-order byte indicating a minor version.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>VMC Capabilities Response</title>
<table frame="all" pgwide="1">
<title>VMC Capabilities Response Message</title>
<?dbhtml table-width="90%" ?><?dbfo table-width="90%" ?>
<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" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x81</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para># HMC&#8217;s</para>
</entry>
<entry>
<para>Pool Size</para>
</entry>
<entry>
<para>MTU</para>
</entry>
<entry>
<para>CRQ Size</para>
</entry>
<entry>
<para>Version (Major/Minor)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the hypervisor in response to the VMC
Capabilities message. This command enables the hypervisor to inform the
management partition of the values it supports. Parameters are identical
to the VMC Capabilities message, with the addition of the following
field:</para>
<para>Status. Zero is success. On failure, one of the following is
returned:</para>
<para>1 - General failure</para>
<para>2 - Invalid version</para>
<para>The hypervisor and the management partition use the minimum value
supported by each side for the parameters negotiated with the
capabilities message exchange.</para>
</section>
</section>
<section>
<title>HMC Interface Buffers</title>
<para>Buffers are used to transfer data between the management partition
and the hypervisor. Many of the HMC Interface messages defined in
following sections indicate buffers that contain data that must be
transferred. Note the following:</para>
<orderedlist>
<listitem>
<para>All buffers exist in the hypervisor memory, and data is moved
between the hypervisor and the management partition by the management
partition issuing H_COPY_RDMA.</para>
</listitem>
<listitem>
<para>To enable the management partition to access each buffer, the
hypervisor must allocate virtual TCEs as well as the actual buffer
storage.</para>
</listitem>
<listitem>
<para>Each buffer is at least the minimum negotiated MTU bytes
long.</para>
</listitem>
<listitem>
<para>Buffers are always owned by either the management partition or
the hypervisor. Management partition-owned buffers are used for messages
(both commands and responses) sent to the hypervisor from the management
partition. The hypervisor-owned buffers are used for messages (both
responses and asynchronous events) sent from the hypervisor to the
management partition.</para>
</listitem>
<listitem>
<para>Each LPM interface message carrying HMC protocol (either
direction) also carries a buffer, and the ownership of this buffer
transfers from sender to receiver.</para>
</listitem>
<listitem>
<para>There are no CRQ responses to the CRQ messages carrying HMC
protocol. The HMC protocol responses are carried in a message sent from
the other direction.</para>
</listitem>
<listitem>
<para>The maximum depth of the buffer pool is the minimum value
negotiated via the capabilities exchange.</para>
</listitem>
<listitem>
<para>For each of the HMC interface commands, Buffer ID is used to
identify the transfer buffer and ranges from 0 to the minimum negotiated
pool size - 1.</para>
</listitem>
<listitem>
<para>There is a separate buffer pool for each LPM connection, each
with the negotiated number of buffers.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>HMC Interface Messages</title>
<para>There are several different HMC Interface messages, as defined in
the following sections. Each CRQ message has a unique HMC Interface
message type, and the HMC Interface message type defines the format for
the remaining 14 bytes of data.</para>
<section>
<title>Interface Open</title>
<table frame="all" pgwide="1">
<title>Interface Open Command Message</title>
<?dbhtml table-width="90%" ?><?dbfo table-width="90%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the management partition as the result of a
management partition device request. It causes the hypervisor to prepare
a set of data buffers for the LPM connection indicated by HMC Idx (HMC
index). A unique HMC Idx would be used if multiple management
applications running concurrently were desired. Before responding to this
command, the hypervisor must provide the management partition with at
least one of these new buffers (see the Add Buffer message defined
below). The HMC Sn (HMC Session) field is used as a session identifier
for the current VMC connection. If the management partition disconnects
(for example as the result of a crash in the LPM application), the next
open of the VMC device will result in the next HMC Sn value in the range
from 1 to 255 being used.</para>
<para>This message is issued after the capabilities exchange has
successfully completed and the hypervisor has issued an Add Buffer
command to create a buffer for the management partition for use in
establishing an LPM connection. The management partition sends the unique
32-byte HMC ID to the hypervisor via an RDMA using the buffer established
by the hypervisor.</para>
</section>
<section>
<title>Interface Open Response</title>
<table frame="all" pgwide="1">
<title>Interface Open Response Message</title>
<?dbhtml table-width="90%" ?><?dbfo table-width="90%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x82</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the hypervisor in response to the Interface
Open message. The status of the open command is returned in the Status
field. Zero is success. On failure, the following is returned:</para>
<para>1 - General failure</para>
<para>When this message is received, the indicated buffer is again
available for management partition use.</para>
</section>
<section>
<title>Interface Close</title>
<table frame="all" pgwide="1">
<title>Interface Close Message</title>
<?dbhtml table-width="90%" ?><?dbfo table-width="90%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x03</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the management partition to terminate an
LPM to hypervisor connection. When this command is sent, the management
partition has quiesced all I/O operations to all buffers associated with
this LPM connection, and has freed any storage for those buffers.</para>
</section>
<section>
<title>Interface Close Response</title>
<table frame="all" pgwide="1">
<title>Interface Close Response Message</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x83</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the hypervisor in response to the LPM
Interface Close message. The status of the close command is returned in
the Status field. Zero is success. On failure, the following is
returned:</para>
<para>1 - General failure</para>
</section>
<section>
<title>Add Buffer</title>
<table frame="all" pgwide="1">
<title>Add Buffer Message</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" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x04</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>hypervisor</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Buffer LIOBA</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This message transfers a buffer from hypervisor ownership to
management partition ownership. The LIOBA is obtained from the virtual
TCE table associated with the hypervisor side of the VMC device, and
points to a buffer of size MTU (as established in the capabilities
exchange).</para>
<para>The hypervisor field is set to 0 if the buffer being added is to be
used by the management partition for messages inbound to the hypervisor,
and to 1 if the buffer being added is to be used for messages outbound
from the hypervisor.</para>
<para>The typical flow for adding buffers:</para>
<orderedlist>
<listitem>
<para>A new LPM connection is opened by the management
partition.</para>
</listitem>
<listitem>
<para>The hypervisor assigns new buffers for the traffic associated
with that connection.</para>
</listitem>
<listitem>
<para>The hypervisor sends VMC Add Buffer messages to the management
partition, informing it of the new buffers.</para>
</listitem>
<listitem>
<para>The hypervisor sends an HMC protocol message (to the LPM
application) notifying it of the new buffers. This informs the
application that it has buffers available for sending HMC
commands.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Add Buffer Response</title>
<table frame="all" pgwide="1">
<title>Add Buffer Response Message</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x84</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the management partition to the hypervisor
in response to the Add Buffer message. The Status field indicates the
result of the command. Zero is success. On failure, one of the following
is returned:</para>
<para>1 - General failure</para>
<para>2 - Invalid HMC Index</para>
<para>3 - Invalid Buffer ID</para>
<para>4 - HMC connection has closed</para>
</section>
<section>
<title>Remove Buffer</title>
<table frame="all" pgwide="1">
<title>Remove Buffer Message</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x05</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This message requests an HMC buffer to be transferred from
management partition ownership to hypervisor ownership. The management
partition may not be able to satisfy the request at a particular point in
time if all its buffers are in use. The management partition requires a
depth of at least one inbound buffer to allow LPM commands to flow to the
hypervisor. It is, therefore, an interface error for the hypervisor to
attempt to remove the management partition's last buffer.</para>
<para>The hypervisor is expected to manage buffer usage with the LPM
application directly and inform the management partition when buffers may
be removed. The typical flow for removing buffers:</para>
<orderedlist>
<listitem>
<para>The LPM application no longer needs a communication path to a
particular hypervisor function. That function is closed.</para>
</listitem>
<listitem>
<para>The hypervisor and the LPM application quiesce all traffic to
that function. The hypervisor requests a reduction in buffer pool
size.</para>
</listitem>
<listitem>
<para>The LPM application acknowledges the reduction in buffer pool
size.</para>
</listitem>
<listitem>
<para>The hypervisor sends a Remove Buffer message to the management
partition, informing it of the reduction in buffers.</para>
</listitem>
<listitem>
<para>The management partition verifies it can remove the buffer. This
is possible if buffers have been quiesced.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Remove Buffer Response</title>
<table frame="all" pgwide="1">
<title>Remove Buffer Response Message</title>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>8 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x85</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent by the management partition to the hypervisor
in response to the Remove Buffer message. The Buffer ID field indicates
which buffer the management partition selected to remove. The Status
field indicates the result of the command. Zero is success. On failure,
the following is returned:</para>
<para>1 - General failure</para>
<para>2 - Invalid HMC Index</para>
<para>3 - No buffer found</para>
</section>
<section>
<title>Signal Message</title>
<table frame="all" pgwide="1">
<title>Signal Message</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" />
<tbody>
<row>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>1B</para>
</entry>
<entry>
<para>1 B</para>
</entry>
<entry>
<para>2 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
<entry>
<para>4 B</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>0x06</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>HMC Sn</para>
</entry>
<entry>
<para>HMC Idx</para>
</entry>
<entry>
<para>Buffer ID</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>Msg Len</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This command is sent between the management partition and the
hypervisor in order to signal the arrival of an HMC protocol message. The
command can be sent by both the management partition and the hypervisor.
It is used for all traffic between the LPM application and the
hypervisor, regardless of who initiated the communication.</para>
<para>There is no response to this message.</para>
</section>
</section>
</section>
<section>
<title>Example Management Partition VMC Driver Interface</title>
<para>This section provides an example for the LPM implementation where a
device driver is used to interface to the VMC device. This driver consists
of a new device, for example /dev/lparvmc, which provides interfaces to
open, close, read, write, and perform ioctl&#8217;s against the VMC
device.</para>
<section>
<title>VMC Interface Initialization</title>
<para>The device driver is responsible for initializing the VMC when the
driver is loaded. It first creates and initializes the CRQ. Next, an
exchange of VMC capabilities is performed to indicate the code version
and number of resources available in both the management partition and
the hypervisor. Finally, the hypervisor requests that the management
partition create an initial pool of VMC buffers, one buffer for each
possible HMC connection, which will be used for LPM session
initialization. Prior to completion of this initialization sequence, the
device returns EBUSY to open() calls. EIO is returned for all open()
failures.</para>
<figure>
<title>VMC Interface Initialization</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-68.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-68.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>VMC Interface Open</title>
<para>After the basic VMC channel
has been initialized, an HMC session level connection can be established.
The application layer performs an open() to the VMC device and executes
an ioctl() against it, indicating the HMC ID (32 bytes of data) for this
session. If the VMC device is in an invalid state, EIO will be returned
for the ioctl(). The device driver creates a new HMC session value
(ranging from 1 to 255) and HMC index value (starting at index 0 and
potentially ranging to 254 in future releases) for this HMC ID. The
driver then does an RDMA of the HMC ID to the hypervisor, and then sends
an Interface Open message to the hypervisor to establish the session over
the VMC. After the hypervisor receives this information, it sends Add
Buffer messages to the management partition to seed an initial pool of
buffers for the new HMC connection. Finally, the hypervisor sends an
Interface Open Response message, to indicate that it is ready for normal
runtime messaging. The following illustrates this VMC flow:</para>
<figure>
<title>VMC Interface Open</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-70.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-70.gif"
format="GIF" scalefit="1" width="86%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>VMC Interface Runtime</title>
<para>During normal runtime, the LPM
application and the hypervisor exchange HMC messages via the Signal VMC
message and RDMA operations. When sending data to the hypervisor, the LPM
application performs a write() to the VMC device, and the driver
RDMA&#8217;s the data to the hypervisor and then sends a Signal Message.
If a write() is attempted before VMC device buffers have been made
available by the hypervisor, or no buffers are currently available, EBUSY
is returned in response to the write(). A write() will return EIO for all
other errors, such as an invalid device state. When the hypervisor sends
a message to the LPM, the data is put into a VMC buffer and an Signal
Message is sent to the VMC driver in the management partition. The driver
RDMA&#8217;s the buffer into the partition and passes the data up to the
appropriate LPM application via a read() to the VMC device. The read()
request blocks if there is no buffer available to read. The LPM
application may use select() to wait for the VMC device to become ready
with data to read.</para>
<figure>
<title>VMC Interface Runtime</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-71.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata fileref="figures/PAPR-71.gif"
format="GIF" contentdepth="100%" scalefit="1" width="55%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>VMC Interface Close</title>
<para>HMC session level connections are
closed by the management partition when the application layer performs a
close() against the device. This action results in an Interface Close
message flowing to the hypervisor, which causes the session to be
terminated. The device driver must free any storage allocated for buffers
for this HMC connection.</para>
<figure>
<title>VMC Interface Close</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-72.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-72.gif"
format="GIF" scalefit="1" width="53%" />
</imageobject>
</mediaobject>
</figure>
</section>
</section>
</chapter>