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

22301 lines
985 KiB
XML
Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?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.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569348_71217">
<title>Virtualized Input/Output</title>
<para>Virtualized I/O is an optional feature of platforms that have
hypervisor support. Virtual I/O (VIO) provides to a given partition the
appearance of I/O adapters that do not have a one to one correspondence with
a physical IOA. The hypervisor uses one of three techniques to realize a
virtual IOA:</para>
<orderedlist>
<listitem>
<para>In the
<emphasis>hypervisor simulated</emphasis> class, the hypervisor may totally
simulate the adapter. For example, this is used in the virtual ethernet (IEEE
VLAN) support (see
<xref linkend="dbdoclet.50569350_23147" />). This technique is applicable to
communications between partitions that are created by a single hypervisor
instance.</para>
</listitem>
<listitem>
<para>In the
<emphasis>partition managed</emphasis> class, a
<emphasis>server</emphasis> partition provides the services of one of its
IOA&#8217;s to a
<emphasis>partner</emphasis> partition(s) (one or more
<emphasis>client</emphasis> partitions<footnote xml:id="pgfId-998495">
<para>The term &#8220;hosted&#8221; is sometimes used for
&#8220;client&#8221; and the term &#8220;hosting&#8221; is sometimes used
for &#8220;server.&#8221; Note that a server IOA or partition can sometimes
also be a client, and vice versa, so the terminology &#8220;client&#8221;
and &#8220;server&#8221; tend to be less confusing than hosted and
hosting.</para>
</footnote> or one or more server partitions). In limited cases, a client may
communicate directly to a client. A server partition provides support to
interpret I/O requests from the partner partition, perform those requests on
one or more of its devices, targeting the partner partition&#8217;s DMA
buffer areas (for example, by using the Remote DMA (RDMA) facilities), and
passing I/O responses back to the partner partition. For example, see
<xref linkend="dbdoclet.50569351_35753" />.</para>
</listitem>
<listitem>
<para>In the
<emphasis>hypervisor managed</emphasis> class, the hypervisor may provide low
level hardware management (error and sub-channel allocation) so that
partition level code may directly manage its assigned sub-channels.</para>
</listitem>
</orderedlist>
<para>This chapter is organized from general to specific. The overall
structure of this architecture is as shown in
<xref linkend="dbdoclet.50569348_68734" />.</para>
<figure xml:id="dbdoclet.50569348_68734">
<title>VIO Architecture Structure</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-33.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-33.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<section>
<title>Terminology used with VIO</title>
<para>Besides the general terminology defined on the first page of this
chapter, <xref linkend="virtio.terms" />
will assist the reader in understanding the content of this chapter.</para>
<table frame="all" pgwide="1" xml:id="virtio.terms">
<title>Terminology used with VIO</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>Term</para>
</entry>
<entry align="center">
<para>Definition</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>VIO</para>
</entry>
<entry>
<para>Virtual I/O. General term for all virtual I/O classes and
virtual IOAs.</para>
</entry>
</row>
<row>
<entry>
<para>ILLAN</para>
</entry>
<entry>
<para>Interpartition Logical LAN. This option uses the
hypervisor simulated class of virtual I/O to provide
partition-to-partition LAN facilities without a real LAN IOA.
See
<xref linkend="dbdoclet.50569350_23147" />.</para>
</entry>
</row>
<row>
<entry>
<para>VSCSI</para>
</entry>
<entry>
<para>Virtual SCSI. This option provides the facilities for
sharing physical SCSI type IOAs between partitions.
<xref linkend="dbdoclet.50569351_35753" />.</para>
</entry>
</row>
<row>
<entry>
<para>Client<?linebreak?>Client VIO model</para>
</entry>
<entry>
<para>This terminology is mainly used with the partition
managed class of VIO. The client, or client partition, is an
entity which generally requests of a server partition, access
to I/O to which it does not have direct access (that is, access
to I/O which is under control of the server partition). Unlike
the server, the client does not provide services to other
partitions to share the I/O which resides in their partition.
However, it possible to have the same partition be both a
server and client partition, but under different virtual IOAs.
The Client VIO model is one where the client partition maps
part of its local memory into an RTCE table (as defined by the
first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>property),
so that the server partition can get access to that
client&#8217;s local memory. An example of this is the VSCSI
client (see
<xref linkend="dbdoclet.50569351_35753" /> for more
information).</para>
</entry>
</row>
<row>
<entry>
<para>Server<?linebreak?>Server VIO model</para>
</entry>
<entry>
<para>This terminology is mainly used with the partition
managed class of VIO. The server, or server partition is an
entity which provides a method of sharing the resources under
its direct control with another partition, virtualizing those
resources in the process. The following defines the Server VIO
model:</para>
<para>The server is a server to a client. An example of this is
the VSCSI client (see
<xref linkend="dbdoclet.50569351_35753" />). In this case, the
Server VIO model is one where the server gets access to the
client partition&#8217;s local memory via what the client
mapped into an RTCE table. This access is done through the
second window pane of the server&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>property,
which is linked to the first window pane of the client&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>property.</para>
</entry>
</row>
<row>
<entry>
<para>Partner partition</para>
</entry>
<entry>
<para>This is &#8220;the other&#8221; partition in a pair of
partitions which are connected via a virtual IOA pair. For
client partitions, the partner is generally the server
(although, in limited cases, client to client connections may
be possible). For server partitions, the partner can be a
client partition or another server partition.</para>
</entry>
</row>
<row>
<entry>
<para>RTCE table</para>
</entry>
<entry>
<para>Remote DMA TCE table. TCE (Translation Control Entry) and
RTCE tables are used to translate I/O DMA operations and
provide protection against improper operations (access to what
should not be accessed or for protection against improper
access modes, like writing to a read only page). More
information on TCEs and TCE tables, which are used for physical
IOAs, can be found in
<xref linkend="dbdoclet.50569328_76588" />. The RTCE table for Remote
DMA (RDMA) is analogous to the TCE table for physical IOAs. The
RTCE table does, however, have a little more information in it
(as placed there by the hypervisor) in order to, among other
things, allow the hypervisor to create links to physical IOA
TCEs that were created from the RTCE table TCEs. A TCE in an
RTCE table is never accessed directly by the partitions
software; only though hypervisor hcall()s. For more information
on RTCE table and operations, see
<xref linkend="dbdoclet.50569348_40629" />, and
<xref linkend="dbdoclet.50569348_51946" />.</para>
</entry>
</row>
<row>
<entry>
<para>Window pane</para>
<para>(<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property)</para>
</entry>
<entry>
<para>The RTCE tables for VIO DMA are pointed to by the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property in
the device tree for each virtual device. This property can have
one, two, or three triples, each consisting of a Logical I/O
Bus Number (LIOBN), phys which is 0, and size. The LIOBN
essentially points to a unique RTCE table (or a unique entry
point into a single table. The phys is a value of 0, indicating
offsets start at 0. The size is the size of the available
address space for mapping memory into the RTCE table. This
architecture talks about these unique RTCE tables as being
window panes within the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.
Thus, there can be up to three window panes for each virtual
IOA, depending on the type of IOA. For more on usage of the
window panes, see
<xref linkend="dbdoclet.50569348_74626" />.</para>
</entry>
</row>
<row>
<entry>
<para>RDMA</para>
</entry>
<entry>
<para>Remote Direct Memory Access is DMA transfer from the
server to its client or from the server to its partner
partition. DMA refers to both physical I/O to/from memory
operations and to memory to memory move operations.</para>
</entry>
</row>
<row>
<entry>
<para>Copy RDMA</para>
</entry>
<entry>
<para>This term refers to when the hypervisor is used (possibly
with hardware assist) to move data between server partition and
client partition memories or between server partition and
partner partition memories. See
<xref linkend="dbdoclet.50569348_15951" />.</para>
</entry>
</row>
<row>
<entry>
<para>Redirected RDMA</para>
</entry>
<entry>
<para>This term refers to when the TCE(s) for a physical IOA
are set up through the use of the RTCE table manipulation
hcall()s (for example, H_PUT_RTCE) such that the client or
partner&#8217;s partition&#8217;s RTCE table (though the second
window pane of the server partition) is used by the hypervisor
during the processing of the hcall() to setup the TCE(s) for
the physical IOA, and then the physical IOA DMAs directly to or
from the client or partner partition&#8217;s memory. See
<xref linkend="dbdoclet.50569348_25634" /> for more
information.</para>
</entry>
</row>
<row>
<entry>
<para>LRDMA</para>
</entry>
<entry>
<para>Stands for Logical Remote DMA and refers to the set of
facilities for synchronous RDMA operations. See also
<xref linkend="dbdoclet.50569348_61656" /> for more information.
LRDMA is a separate option.</para>
</entry>
</row>
<row>
<entry>
<para>Command/Response Queue (CRQ)</para>
</entry>
<entry>
<para>The CRQ is a facility which is used to communicate
between partner partitions. Transport events which are signaled
from the hypervisor to the partition are also reported in this
queue.</para>
</entry>
</row>
<row>
<entry>
<para>Subordinate CRQ (Sub-CRQ)</para>
</entry>
<entry>
<para>Similar to the CRQ, except with notable differences (See
<xref linkend="dbdoclet.50569348_26160" />).</para>
</entry>
</row>
<row>
<entry>
<para>Reliable Command/Response Transport</para>
</entry>
<entry>
<para>This is the CRQ facility used for synchronous VIO
operations to communicate between partner partitions. Several
hcall()s are defined which allow a partition to place an entry
on the partner partition&#8217;s queue. The firmware can also
place transport change of status messages into the queue to
notify a partition when the connection has been lost (for
example, due to the other partition crashing or deregistering
its queue). See
<xref linkend="dbdoclet.50569348_48491" /> for more
information.</para>
</entry>
</row>
<row>
<entry>
<para>Subordinate CRQ Transport</para>
</entry>
<entry>
<para>This is the Sub-CRQ facility used for synchronous VIO
operations to communicate between partner partitions when the
CRQ facility by itself is not sufficient. The Subordinate CRQ
Transport never exists without a corresponding Reliable
Command/Response Transport. See
<xref linkend="dbdoclet.50569348_28179" /> for more
information.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="dbdoclet.50569348_91721">
<title>VIO Architectural Infrastructure</title>
<para>VIO is used in conjunction with the Logical Partitioning option as
described in
<xref linkend="dbdoclet.50569344_14591" />. For each of a platform&#8217;s
partitions, the number and type of VIO adapters with the associated
interpartition communications paths (if any are defined). These definitions
take the architectural form of VIO adapters and are communicated to the
partitions as device nodes in their OF device tree. Depending upon the
specific virtual device, their device tree node may be found as a child of
<emphasis role="bold"><literal>/</literal></emphasis> (the root node) or in the VIO sub-tree (see
below).</para>
<para>The VIO infrastructure provides several primitives that may be used
to build connections between partitions for various purposes (that is, for
various virtual IOA types). These primitives include:</para>
<itemizedlist>
<listitem>
<para>A Command/Response Queue (CRQ) facility which provides a pipe
between partitions. A partition can enqueue an entry on its partner&#8217;s
CRQ for processing by that partner. The partition can set up the CRQ to
receive an interrupt when the queue goes from empty to non-empty, and hence
this facility provides a method for an inter-partition interrupt.</para>
</listitem>
<listitem>
<para>A Subordinate CRQ (Sub-CRQ) facility that may be used in
conjunction with the CRQ facility, when the CRQ facility by itself is not
sufficient. That is, when more than one queue with more than one interrupt
is required by the virtual IOA.</para>
</listitem>
<listitem>
<para>An extended TCE table called the RTCE table which allows a
partition to provide &#8220;windows&#8221; into the memory of its partition
to its partner partition, while maintaining addressing and access control
to its memory.</para>
</listitem>
<listitem>
<para>Remote DMA services that allow a server partition to transfer data
to a partner partition&#8217;s memory via the RTCE table window panes. This
allows a device driver in a server partition to efficiently transfer data
to and from a partner, which is key in sharing of an IOA in the server
partition with its partner partition.</para>
</listitem>
</itemizedlist>
<para>In addition to the virtual IOAs themselves, this architecture defines
a virtual host bridge, and a virtual interrupt source controller. The
virtual host bridge roots the VIO sub-tree. The virtual interrupt source
controller provides the consistent syntax for communicating the interrupt
numbers the partition&#8217;s OS sees when the virtual IOAs signal an
interrupt.</para>
<para>The general VIO infrastructure is defined in
<xref linkend="dbdoclet.50569348_21877" />. There are additional
infrastructures requirements for the partition managed class based on the
Synchronous VIO model. See
<xref linkend="dbdoclet.50569348_51946" />.</para>
<section xml:id="dbdoclet.50569348_21877">
<title>VIO Infrastructure - General</title>
<para>This section describes the general OF device tree structure for
virtual IOAs and describes in more detail window panes, as well as
describing the interrupt control aspects of virtual IOAs.</para>
<section xml:id="sec_vdevice_node_prop">
<title>Properties of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> OF Tree Node</title>
<para>Most VIO adapters are represented in the OF device tree as children
of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node (child of the root node). While the
vdevice sub-tree is the preferred architectural home for VIO adapters,
selected devices for historical reasons, are housed outside of the
vdevice sub-tree.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vdevice_node_prop"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold"><literal>/vdevice</literal></emphasis> node must contain the properties as defined
in <xref linkend="dbdoclet.50569348_40283" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_40283">
<title>Properties of the <emphasis role="bold"><literal>/vdevice</literal></emphasis> Node</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>,
specifying the virtual device name, the value shall be
<emphasis role="bold"><literal>&#8220;vdevice&#8221;</literal></emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>,
specifying the virtual device type, the value shall be
<emphasis role="bold"><literal>&#8220;vdevice&#8221;</literal></emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis>
<xref linkend="dbdoclet.50569387_45524" />,</emphasis> specifying
the virtual device programming models, the value shall include
<emphasis role="bold"><literal>&#8220;IBM,vdevice&#8221;</literal></emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>The location code is meaningless unless one is doing
dynamic reconfiguration as in the children of this node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>,
the value shall be 0. No child of this node takes
space in the address map as seen by the owning
partition.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>,
the value shall be 1.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>,
the value shall be 2. The first cell contains the
interrupt# as will appear in the XIRR and is used as input to
interrupt RTAS calls. The second cell contains the value 0
indicating a positive edge sense</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-map-mask&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name that defines the interrupt
number(s) and range(s) handled by this unit.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>These will probably be needed for IB virtual
adapters.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>The
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node appears to contain an
interrupt controller.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Refers to the DR slots -- the number provided is the
maximum number of slots that can be configured which is limited
by, among other things, the RTCE tables allocated by the
hypervisor.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Value of -1 to indicate that no power manipulation is
possible or needed.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Value of
<emphasis role="bold"><literal>&#8220;SLOT&#8221;</literal></emphasis>. Any virtual IOA can
fit into any virtual slot.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>The virtual location code (see
<xref linkend="dbdoclet.50569341_32742" />)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>When present replaces the <emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> properties.
This single property is a consolidation of the four pre-existing properties
and contains all of the required information.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>The maximum transfer size for H_SEND_LOGICAL_LAN and
H_COPY_RDMA hcall()s. Applies to all VIO which are children of
the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node. Minimum value is 128
KB.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="dbdoclet.50569348_40629">
<title>RTCE Table and Properties of the Children of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> Node</title>
<para>This architecture defines an extended type of TCE table called a
Remote DMA TCE (RTCE) table. An RTCE table is one that is not directly
used by the hardware to translate an I/O adapter&#8217;s DMA addresses,
but is used by the hypervisor to translate a partition&#8217;s I/O
addresses. RTCE tables have extra data, compared with a standard TCE
table, to help firmware manage the use of its mappings. A partition
manages the entries for its memory that is to be the target for I/O
operations in the RTCE table using the TCE manipulation hcall()s,
depending on the type of window pane. More on this later in this section.
On platforms implementing the CRQ LRDMA options, these hcall()s are
extended to understand the format of the RTCE table via the LIOBN
parameter that is used to address the specific window pane within an RTCE
table<footnote xml:id="pgfId-999363">
<para>One could also think of each LIOBN pointing to a separate RTCE
table, rather than window panes within an RTCE table.</para>
</footnote>.</para>
<para>Children of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node that support operations which use RTCE
tables (for example, RDMA) contain the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. This
property contains one or more (logical-I/O-bus-number, phys, size)
triple(s). Each triple represents one window pane in an RTCE table which
is available to this virtual IOA. The phys value is 0, and hence the
logical I/O bus number (LIOBN) points to a unique range of TCEs in the
RTCE table which are assigned to this window pane (LIOBN), and hence the
I/O address for that LIOBN begin at 0.</para>
<para>The LIOBN is an opaque handle which references a window pane within
an RTCE table. Since this handle is opaque, its internal structure is not
architected, but left to the implementation&#8217;s discretion. However,
it is the architectural intent that the LIOBN be an indirect reference to
the RTCE table through a hypervisor table that contains management
variables, allowing for movement of the RTCE table and table format
specific access methods. The partition uses an I/O address as an offset
relative to the beginning of the LIOBN, as part of any I/O request to
that memory mapped by that RTCE table&#8217;s TCEs. A server partition
appends its version of the LIOBN for the partner partition&#8217;s RTCE
table that represents the partner partition&#8217;s RTCE table which it
received through the second entry in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property associated
with server partition&#8217;s virtual IOA&#8217;s device tree node (for
example, see
<xref linkend="dbdoclet.50569348_40283" />). The mapping between the
LIOBN in the second pane of a server virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property and the
corresponding partner partition IOA&#8217;s RTCE table is made when the
CRQ successfully completes registration.</para>
<para>The window panes and the hcall()s that are applicable to those
panes, are defined and used as indicated in
<xref linkend="dbdoclet.50569348_74626" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_74626">
<title>VIO Window Pane Usage and Applicable Hcall()s</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="30*" />
<colspec colname="c4" colwidth="30*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Window Pane (Which Triple)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Hypervisor Simulated Class</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Client VIO Model</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Server VIO Model</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry morerows="1">
<para>First</para>
</entry>
<entry valign="top">
<itemizedlist>
<listitem>
<para>I/O address range which is available to map local
partition memory for use by the hypervisor</para>
</listitem>
</itemizedlist>
</entry>
<entry valign="top">
<itemizedlist>
<listitem>
<para>I/O address range which is available to map local
partition memory to make it available to the hypervisor use
(access to the CRQ and any Sub-CRQs).</para>
</listitem>
<listitem>
<para>For clients which support RDMA operations from their
partner partition to their local memory (for example, VSCSI),
this I/O address range is available to map local partition
memory to make it available to the server partition, and this
pane gets mapped to the second window pane of the partner
partition (client/server relationship).</para>
</listitem>
</itemizedlist>
</entry>
<entry valign="top">
<itemizedlist>
<listitem>
<para>I/O address range which is available to map local
partition memory for use by the hypervisor (for access by
H_COPY_RDMA requests, and for access to the CRQ, any
Sub-CRQs).</para>
</listitem>
<listitem>
<para>This window is not available to any other
partition.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry nameend="c4" namest="c2" align="center">
<para>Applicable hcall()s: H_PUT_TCE, H_GET_TCE,
H_PUT_TCE_INDIRECT, H_STUFF_TCE</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Second</para>
</entry>
<entry align="center">
<para>Does not exist</para>
</entry>
<entry align="center">
<para>Does not exist</para>
</entry>
<entry valign="top">
<itemizedlist>
<listitem>
<para>I/O address range which corresponds to a window pane of
the partner partition: linked to the first window pane for
Client/Server model connections.</para>
</listitem>
<listitem>
<para>Used to get access to the partner partition&#8217;s
memory from the hypervisor that services the local partition
for use as source or destination in Copy RDMA requests or for
redirected DMA operations (for example, H_PUT_RTCE).</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry nameend="c4" namest="c2" align="center">
<para>Applicable hcall()s: H_PUT_RTCE, H_REMOVE_RTCE and
H_PUT_RTCE_INDIRECT</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property is the per
device equivalent of the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property found in nodes
representing bus bridges.</para>
<para>Children of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node contain virtual location codes in their
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> properties. The invariant
assignment number is uniquely generated when the virtual IOA is assigned
to the partition and remains invariably associated with that virtual IOA
for the duration of the partition definition. For more information, see
<xref linkend="dbdoclet.50569341_32742" />.</para>
</section>
<section xml:id="dbdoclet.50569348_27549">
<title>VIO Interrupt Control</title>
<para>There are two hcall()s that work in conjunction with the RTAS calls
<emphasis>ibm,int-on</emphasis>,
<emphasis>ibm,int-off</emphasis>,
<emphasis>ibm,set-xive</emphasis> and
<emphasis>ibm,get-xive</emphasis>, which manage the state of the
interrupt presentation controller logic. These hcall()s provide the
equivalent of IOA control registers used to control IOA interrupts. The
usage of these two hcall()s is summarized in
<xref linkend="dbdoclet.50569348_19858" />. The detail of the
H_VIO_SIGNAL is shown after this table and the detail of the applicable
H_VIOCTL subfunctions can be found in
<xref linkend="dbdoclet.50569348_56284" />,
<xref linkend="dbdoclet.50569348_22810" />, and
<xref linkend="dbdoclet.50569348_68387" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_19858">
<title>VIO Interrupt Control hcall() Usage</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<colspec colname="c4" colwidth="25*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Interrupt From</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Virtual IOA Definition does</emphasis>
<emphasis>not</emphasis>
<emphasis role="bold">Include Sub-CRQs</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Virtual IOA Definition</emphasis>
<emphasis>Includes</emphasis>
<emphasis role="bold">Sub-CRQs</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Interrupt Number Obtained
From</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>CRQ</para>
</entry>
<entry>
<para>H_VIO_SIGNAL</para>
</entry>
<entry>
<para>H_VIO_SIGNAL<?linebreak?>
or<?linebreak?>
H_VIOCTL</para>
</entry>
<entry>
<para>OF device tree
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property</para>
</entry>
</row>
<row>
<entry>
<para>Sub-CRQ</para>
</entry>
<entry>
<para>Not Applicable</para>
</entry>
<entry>
<para>H_VIOCTL</para>
</entry>
<entry>
<para>H_REG_SUB_CRQ hcall()</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<section xml:id="dbdoclet.50569348_53470">
<title>H_VIO_SIGNAL</title>
<para>This H_VIO_SIGNAL hcall() manages the interrupt mode of a virtual
adapter&#8217;s CRQ interrupt signalling logic. There are two modes:
Disabled, and Enabled.</para>
<para>The first interrupt of the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property is for the
CRQ.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the input parameters are */
/* invalid */
/* H_Hardware: A hardware problem prevented completion of */
/* the operation*/
hcall ( const int64 H_VIO_SIGNAL, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA&#8217;s device tree */
/* node */
uint64 mode /* 0=Disabled, 1=Enabled with each bit representing a */
/* possible interrupt*/
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: unit address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>mode:</para>
<itemizedlist>
<listitem>
<para>Bit 63 controls the first interrupt specifier given in the
virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property, and bit 62 the
second. High order bits not associated with an interrupt source as
defined in the previous sentence should be set to zero by the caller and
ignored by the hypervisor.</para>
</listitem>
<listitem>
<para>A bit value of 1 enables the specified interrupt, a bit value of
0 disables the specified interrupt.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that the unit address belongs to the partition and to a
vdevice IOA, else H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the mode is one of those defined, else
H_Parameter.</para>
</listitem>
<listitem>
<para>Establish the specified mode.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="dbdoclet.50569348_66872">
<title>General VIO Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform must be running in
LPAR mode.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform&#8217;s OF device
tree must include, as a child of the
<emphasis role="bold"><literal>root</literal></emphasis> node, a node of type
<emphasis role="bold"><literal>vdevice</literal></emphasis> as the parent of a sub-tree representing the
virtual IOAs assigned to the partition (see
<xref linkend="dbdoclet.50569368_91814" /> for details).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node must contain properties as defined in
<xref linkend="dbdoclet.50569348_40283" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> If the platform is going to
limit the size of virtual I/O data copy operations (e.g.,
H_SEND_LOGICAL_LAN and H_COPY_RDMA), then the platform&#8217;s
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node must contain the
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis> property, and
the value of this property must be at least 128 KB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The interrupt server numbers for
all interrupt source numbers, virtual and physical, must come from the
same name space and are defined by the
<emphasis role="bold"><literal>&#8220;ibm,interrupt-buid-size&#8221;</literal></emphasis> property in the
<emphasis role="bold"><literal>PowerPC External Interrupt Presentation
Controller</literal></emphasis> Node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The virtual interrupts for all
children of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node must, upon transfer of control to the
booted partition program, be masked as would be the result of an
<emphasis>ibm,int-off</emphasis> RTAS call specifying the virtual
interrupt source number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options with the Reliable Command/Response
option:</emphasis> The platform must specify the CRQ interrupt as the
first interrupt in the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property for a virtual
IOA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the SMC options:</emphasis>
The platform must specify the ASQ interrupt as the second interrupt in the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property for a virtual IOA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform must implement the
H_VIO_SIGNAL hcall() as defined in
<xref linkend="dbdoclet.50569348_27549" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform must assign an
invariant virtual location code to each virtual IOA as described in
<xref linkend="dbdoclet.50569341_32742" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis>(Requirement Number Reserved For Compatibility)</emphasis>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The
<emphasis role="bold"><literal>phys</literal></emphasis> of each
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property triple
(window pane) must have a value of zero and the LIOBN must be
unique.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> While the architectural
definition of LIOBN would allow the definition of one logical I/O bus
number (LIOBN) for all RTCE tables (IOBA ranges separating IOAs), such an
implementation is not permitted for the VIO option, which requires a
unique LIOBN (at least per partition preferably platform wide) for each
virtual IOA window pane. Such designs allow the LIOBN handle to be used
to validate access rights, and allows each subsequent I/O bus address
range to start at zero, providing maximum accommodation for 32 bit
OS&#8217;s.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_86469">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis>
For the server
partition, there must exist two triples (two window panes) in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property and the size
field of the second triple (second window pane) of an
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property must be
equal to the size field of the corresponding first triple (first window
pane) of the associated partner partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the SMC option:</emphasis>
There must exist three triples (three window panes) in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property of all partitions which contain an SMC virtual IOA, and the size field
of the second triple (second window pane) of an
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property must be equal to the
size field of the corresponding third triple (third window pane) of the associated partner partition’s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_77308">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis>
RTCE tables for
virtual IOAs, as pointed to by the partitions&#8217; first window pane of
the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, and the
TCEs that they contain (as built by the TCE hcall()s) must be persistent
across partner partition reboots and across partner partition deregister
(free)/re-register operations, even when the partition which connects
after one deregisters is a different partition, and must be available to
have TCEs built in them by said partition, as long as that partition
still owns the corresponding virtual IOA (an LRDR operation which removes
the IOA will also remove the RTCE table).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The connection between the
second window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property for a
partition and its corresponding window pane in the partner partition
(first window pane) must be broken by the platform when either partition
deregisters its CRQ or when either partition terminates, and the platform
must invalidate any redirected TCEs copied from the said second window
pane (for information on invalidation of TCEs, see
<xref linkend="dbdoclet.50569348_69987" />).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The following window panes of
the <emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property, when they exist, must support the following specified hcall()s, when they are
implemented:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>For the first window pane: H_PUT_TCE, H_GET_TCE,
H_PUT_TCE_INDIRECT, H_STUFF_TCE</para>
</listitem>
<listitem>
<para>For the second window pane: H_PUT_RTCE, H_REMOVE_RTCE,
H_PUT_RTCE_INDIRECT</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_55767">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis>
The platform must not prohibit the server and partner partition, or client and partner
partition, from being the same partition, unless the user interface used
to setup the virtual IOAs specifically disallows such
configurations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> Any child node of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node that is not defined by this
architecture must contain the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property.</para>
<para>
<emphasis role="bold">Implementation Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>Relative to Requirement
<xref linkend="dbdoclet.50569348_55767" />, partner partitions being the
same partition makes sense from a product development standpoint.</para>
</listitem>
<listitem>
<para>The
<emphasis>ibm,partner-control</emphasis> RTAS call does not make sense if
the partner partitions are the same partition.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66872"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all VIO options:</emphasis> The platform must implement the
H_VIOCTL hcall() following the syntax of
<xref linkend="dbdoclet.50569348_33176" /> and semantics specified by
<xref linkend="dbdoclet.50569348_61979" />.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569348_67470">
<title>Shared Logical Resources</title>
<para>The sharing of resources, within the boundaries of a single
coherence domain, owned by a partition owning a server virtual IOA by its
clients (those owning the associated client virtual IOAs) is controlled
by the hcall()s described in this section. The owning partition retains
control of and access to the resources and can ask for their return or
indeed force it. Refer to
<xref linkend="dbdoclet.50569348_75708" /> for a graphic representation of
the state transitions involved in sharing logical resources.</para>
<figure xml:id="dbdoclet.50569348_75708">
<title>Shared Logical Resource State Transitions</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-58.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-58.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>Owners of resources can grant, to one or more client
partitions, access to any of its resources. A client partition being
defined as a partition with which the resource owner is authorized to
register a CRQ, as denoted via an OF device tree virtual IOA node.
Granting access is accomplished by requesting that the hypervisor
generate a specific cookie for that resource for a specific sharing
partition. The cookie value thus generated is unique only within the
context of the partition being granted the resource and is unusable for
gaining access to the resource by any other partition. This unique cookie
is then communicated via some inter partition communications channel,
most likely the authorized Command Response Queue. The partner partition
then accepts the logical resource (mapping it into the accepting
partition&#8217;s logical address space). The owning partition may grant
shared access of the same logical resource to several clients (by
generating separate cookies for each client). During the time the
resource is shared, both the owner and the sharer(s) have access to the
logical resource, the software running in these partitions use private
protocols to synchronize control access. Once the resource has been
accepted into the client&#8217;s logical address space, the resource can
be used by the client in any way it wishes, including granting it to one
of its own clients. When the client no longer needs access to the shared
logical resource, it destroys any virtual mappings it may have created
for the logical resource and returns the logical resource thus unmapping
it from its logical address space. The client program could, subsequently
accept the logical resource again (given that the cookie is still valid).
To complete the termination of sharing, the owner partition rescinds the
cookie describing the shared resource. Normally a rescind operation
succeeds only if the client has returned the resource, however, the owner
can force the rescind in cases where it suspects that the client is
incapable of gracefully returning the resource.</para>
<para>In the case of a forced rescind, the hypervisor marks the client
partition&#8217;s logical address map location corresponding to the
shared logical resource such that any future hcall() that specifies the
logical address fails with an H_RESCINDED return code. The hypervisor
then ensures that the client partition&#8217;s translation tables contain
no references to a physical address of the shared logical
resource.</para>
<para>Should the server partition fail, the hypervisor automatically
notifies client partitions of the fact via the standard CRQ event
message. In addition, the hypervisor recovers any outstanding shared
logical resources prior to restarting the server partition. This recovery
is proceeded by a minimum of two seconds of delay to allow the client
partitions time to gracefully return the shared logical resources, then
the hypervisor performs the equivalent of a forced rescind operation on
all the server partition&#8217;s outstanding shared logical
resources.</para>
<para>This architecture does not specify a method of implementation,
however, for the sake of clarifying the specified function, the following
example implementation is given, refer to
<xref linkend="dbdoclet.50569348_51753" />. Assume that the hypervisor
maintains for each partition a logical to physical translation table (2)
(used to verify the partition&#8217;s virtual to logical mapping
requests). Each logical resource (4) mapped within the logical to real
translation table has associated with it a logical resource control
structure (3) (some of the contents of this control structure are defined
in the following text). The original logical resource control structures
(3) describe the standard logical resources allocated to the partition
due to the partition&#8217;s definition, such as one per Logical Memory
Blocks (LMB), etc.</para>
<para>The platform firmware, when creating the OF device tree for a given
partition knows the specific configuration of virtual IOAs with the
associated quantity of the various types of logical resources types for
each virtual IOA. From that knowledge, it understands the number and type
of resources that must be shared between the server and client partitions
and therefore the number of control structures that will be needed. When
an owning partition grants access to a subset of one of its logical
resources to another partition, the hypervisor chooses a logical resource
control structure to describe this newly granted resource (6), (as stated
above, the required number of these control structures were allocated
when the client virtual IOA was defined) and attaches it to the
grantee&#8217;s base partition control structure (5). This logical
resource control structure is linked (9) to the base logical resource
control structure (3) of the resource owner. Subsequently the
grantee&#8217;s OS may accept the shared logical resource (4) mapping it
(7) into the grantee&#8217;s partition logical to physical map table (8).
This same set of operations may subsequently be performed for other
partition(s) (10). The shared resource is always a subset (potentially
the complete subset) of the original. Once a partition (10) has accepted
a resource, it may subsequently grant a subset of that resource to yet
another partition (14), here the hypervisor creates a logical resource
control structure (13) links it (12) to the logical resource control
structure (11) of the granting partition (10) that is in turn linked (9)
to the owner&#8217;s logical resource control structure (3).</para>
<para>&#160;</para>
<figure xml:id="dbdoclet.50569348_51753">
<title>Example Implementation of Control Structures
for Shared Logical Resources</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-59.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-59.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>For the OS to return the logical resource represented by
control structure (11), the grant represented by control structure (13)
needs to be rescinded. This is normally accomplished only after the OS
that is running partition (14) performs a return operation, either
because it has finished using the logical resource, or in response to a
request (delivered by inter partition communications channel) from the
owner. The exceptions are in the case that either partition terminates
(the return operation is performed by the hypervisor) and a
non-responsive client (when the granter performs a forced rescind). A
return operation is much like a logical resource dynamic reconfiguration
isolate operation, the hypervisor removes the logical resource from the
partition&#8217;s logical to physical map table, to prevent new virtual
to physical mappings of the logical resource, then ensures that no
virtual to physical mappings of the logical resource are outstanding
(this can either be accomplished synchronously by checking map counts
etc. or asynchronously prior to the completion of the rescind operation.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_67470"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Shared Logical Resource option:</emphasis> The platform
must implement the hcall-logical-resource function set following the
syntax and semantics of the included hcall(s) as specified in:</para>
<para><xref linkend="dbdoclet.50569348_71928" />,</para>
<para><xref linkend="dbdoclet.50569348_37799" />,</para>
<para><xref linkend="dbdoclet.50569348_74094" />, and</para>
<para><xref linkend="dbdoclet.50569348_58491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_67470"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Shared Logical Resource option:</emphasis> In the event
that the partition owning a granted shared logical resource fails, the
platform must wait for a minimum of 2 seconds after notifying the client
partitions before recovering the shared resources via an automatic
H_RESCIND_LOGICAL (forced) operation.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569348_71928">
<title>H_GRANT_LOGICAL</title>
<para>This hcall() creates a cookie that represents the specific instance
of the shared object. That is, the specific subset of the original
logical resource to be shared with the specific receiver partition. The
owning partition makes this hcall() in preparation for the sharing of the
logical resource subset with the receiver partition. The resulting cookie
is only valid for the specified receiver partition.</para>
<para>The caller needs to understand the bounds of the logical resource
being granted, such as for example, the logical address range of a given
LMB. The generated cookie does not span multiple elemental logical
resources (that is resources represented by their own Dynamic
Reconfiguration Connector). If the owner wishes to share a range of
resources that does span multiple elemental logical resources, then the
owner uses a series of H_GRANT_LOGICAL calls to generate a set of
cookies, one for each subset of each elemental logical resource to be
shared.</para>
<para>The &#8220;logical&#8221; parameter identifies the starting
&#8220;address&#8221; of the subset of the logical resource to be shared.
The form of this &#8220;address&#8221; is resource dependent, and is
given in
<xref linkend="dbdoclet.50569348_92077" />.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Hardware: Operation failed because of hardware error */
/* H_Parameter: One or more parameters were in error */
/* H_Permission: A grant restriction precludes the operation*/
/* H_RESCINDED: A specified parameter refers to a rescinded */
/* shared logical resource*/
/* H_NOMEM: Operation failed due to lack of hypervisor */
/* resources */
hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a */
/* shared logical resource */
uint64 flags, /* Resource type: */
/* Main store */
/* MMIO space */
/* Interrupt Sources */
/* DMA window panes*/
/* Inter Processor Interrupt ports */
/* Access restriction control bits (No R/W re-grant) */
uint64 logical-hi, /* identifier (storage logical address, LIOBN) */
uint64 logical-lo, /* identifier (storage logical address, interrupt */
/* source #, IOBA) */
uint64 length, /* The number of fundamental logical elements -- units per */
/* resource type */
uint64 unit-address /* As specified in the Virtual IOA’s device tree node */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_92077">
<title>Format of H_GRANT_LOGICAL parameters</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="10*" />
<colspec colname="c4" colwidth="35*" />
<colspec colname="c5" colwidth="35*" />
<thead valign="middle">
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis role="bold">Flags subfunction code (bits 16-23)
value:</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Access Restriction</para>
</entry>
<entry>
<para>Bits 16-19</para>
</entry>
<entry nameend="c5" namest="c3">
<para>The defined bits in this field have
independent meanings, and may appear in combination with all
other bits unless specifically disallowed. (an x in the
binary field indicates that the bit can take on a value of 0
or 1)
</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>0b1xxx</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Read access inhibited (The grantee may
not read from or grant access to read from this logical
resource.)</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>0bx1xx</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Write access inhibited (The grantee may
not write to or grant access to write to this logical
resource.)
</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>0bxx1x</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Re-Grant rights inhibited (the grantee
may not grant access to this logical resource to a subsequent
client.)
</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>0bxxx1</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Reserved calling software should set
this bit to zero. Firmware returns H_Parameter if
set.
</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">Logical Resource</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Supported Combinations</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Bits 20-23</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">&#8220;address&#8221;
description</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">&#8220;length&#8221;
description</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>System Memory</para>
</entry>
<entry>
<para>0bxxx0</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Logical Address (as would be used in H_ENTER) in
logical-lo; logical-hi not used (should be = 0)</para>
</entry>
<entry>
<para>Bytes in units of 4 K on 4 K boundaries (low order 12
bits = 0)</para>
</entry>
</row>
<row>
<entry>
<para>MMIO Space</para>
</entry>
<entry>
<para>0bxxx0</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Logical Address (as would be used in H_ENTER) in
logical-lo; logical-hi not used (should be = 0)</para>
</entry>
<entry>
<para>Bytes in units of 4 K on 4 K boundaries (low order 12
bits = 0)</para>
</entry>
</row>
<row>
<entry>
<para>Interrupt Source</para>
</entry>
<entry>
<para>0b00x0</para>
</entry>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>24 bit Interrupt # (as would be used in
<emphasis>ibm,get-xive</emphasis>) in low order 3 bytes in
logical-lo; logical-hi not used (should be = 0)</para>
</entry>
<entry>
<para>value=1 (the logical resource is one indivisible
unit)</para>
</entry>
</row>
<row>
<entry>
<para>DMA Window Pane
<footnote>
<para><emphasis role="bold">Note:</emphasis> The DMA window only refers to physical DMA
windows not virtual DMA windows. Virtual DMA windows can be
directly created with a client virtual IOA definition and
need not be shared with those of the server.
</para></footnote>
</para>
</entry>
<entry>
<para>0b00x0</para>
</entry>
<entry>
<para>0x5</para>
</entry>
<entry>
<para>32 bit LIOBN in logical-hi; with a 64 bit IOBA
logical-lo</para>
</entry>
<entry>
<para>Bytes of IOBA in units of 4 K on 4 K boundaries (low
order 12 bits = 0)</para>
</entry>
</row>
<row>
<entry>
<para>Interprocessor Interrupt Port</para>
</entry>
<entry>
<para>0b00x0</para>
</entry>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>Processor Number. (As from the processor&#8217;s Unit ID)
in logical-lo; logical-hi not used (should be = 0).</para>
</entry>
<entry>
<para>value=1 (the logical resource is one indivisible
unit)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>unit-address: The unit address of the virtual IOA associated with
the shared logical resource, and thus the partner partition that is to
share the logical resource.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Verify that the flags parameter specifies a supported logical
resource type, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Verify that the logical address validly identifies a logical
resource of the type specified by the flags parameter and owned/shared by
the calling partition, else return H_Parameter; unless:</para>
<itemizedlist>
<listitem>
<para>The logical address&#8217;s page number represents a page that
has been rescinded by the owner, then return H_RESCINDED.</para>
</listitem>
<listitem>
<para>There exists a grant restriction on the logical resource, then
return H_Permission.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Verify that the length parameter is of valid form for the
resource type specified by the flags parameter and that it represents a
subset (up to the full size) of the logical resource specified by the
logical address parameter, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Verify that the unit-address is for a virtual IOA owned by the
calling partition, else return H_Parameter.</para>
</listitem>
<listitem>
<para>If the partner partition&#8217;s client virtual IOA has
sufficient resources, generate hypervisor structures to represent, for
hypervisor management purposes, including any grant restrictions, the
specified shared logical resource, else return H_NOMEM.</para>
</listitem>
<listitem>
<para>Generate a cookie associated with the hypervisor structures
created in the previous step that the partner partition associated with
the unit-address can use to reference said structures via the
H_ACCEPT_LOGICAL and H_RETURN_LOGICAL hcall()s and the calling partition
can use to reference said structures via the H_RESCIND_LOGICAL
hcall().</para>
</listitem>
<listitem>
<para>Place the cookie generated in the previous step in R4 and return
H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_37799">
<title>H_RESCIND_LOGICAL</title>
<para>This hcall() invalidates a logical sharing as created by
H_GRANT_LOGICAL above. This operation may be subject to significant
delays in certain circumstances. Callers may experience an extended
series of H_PARTIAL returns prior to successful completion of this
operation.</para>
<para>If the sharer of the logical resource has not successfully
completed the H_RETURN_LOGICAL operation on the shared logical resource
represented by the specified cookie, the H_RESCIND_LOGICAL hcall() fails
with the H_Resource return code unless the &#8220;force&#8221; flag is
specified. The use of the &#8220;force&#8221; flag increases the
likelihood that a series of H_PARTIAL returns will be experienced prior
to successful completion. The &#8220;force&#8221; flag also causes the
hcall() to recursively rescind any and all cookies that represent
subsequent sharing of the logical resource. That is, if the original
client subsequently granted access to any or all of the logical resource
to a client, those cookies and any other subsequent grants are also
rescinded.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Hardware: Operation failed because of hardware error */
/* H_Parameter: One or more parameters were in error */
/* H_Resource: The operation failed because resource is in */
/* use by the sharer */
/* H_PARTIAL: Rescind in progress call later */
hcall ( const uint64 H_RESCIND_LOGICAL, /* Invalidates a cookie representing a */
/* shared logical resource */
uint64 flags, /* force (ignore resource in use - remove sharer’s access) */
uint64 cookie /* cookie representing the shared resource */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>flags: The flags subfunction code field (bits 16-23) two values are
defined 0x00 &#8220;normal&#8221;, and 0x01 &#8220;forced&#8221;.</para>
<para>cookie: The handle returned by H_GRANT_LOGICAL representing the
logical resource to be rescinded.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Verify that the cookie parameter references an outstanding
instance of a shared logical resource owned/accepted by the calling
partition, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Verify that the flags parameter is one of the supported values,
else return H_Paramter.</para>
</listitem>
<listitem>
<para>If the &#8220;force&#8221; flag is specified<footnote xml:id="pgfId-1200393">
<para>Implementations should provide mechanisms to ensure that reserved
flag field bits are zero, to improve performance, implementations may
chose to activate this checking only in &#8220;debug&#8221; mode. The
mechanism for activating an implementation dependent debug mode is
outside of the scope of this architecture.</para>
</footnote>, then: perform the functions of H_RETURN_LOGICAL (cookie) as
if called by the client partition. Note this involves forced rescinding
any cookies generated by the client partition that refer to the logical
resource referenced by the original cookie being rescinded.</para>
</listitem>
<listitem>
<para>If the client partition has the resource referenced by cookie is
in the available for mapping via its logical to physical mapping table
(the resource was accepted and not returned), return H_Resource.</para>
</listitem>
<listitem>
<para>Verify that resource reference by cookie is not mapped by the
client partition, else return H_PARTIAL.</para>
</listitem>
<listitem>
<para>Hypervisor reclaims control structures referenced by cookie and
returns H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_74094">
<title>H_ACCEPT_LOGICAL</title>
<para>The H_ACCEPT_LOGICAL hcall() maps the granted logical resource into
the client partition&#8217;s logical address space. To provide the most
compact client logical address space, the hypervisor maps the resource
into the lowest applicable logical address for the referenced logical
resource type, consistent with the resource&#8217;s size and the resource
type&#8217;s constraints upon alignment etc. The chosen logical address
for the starting point of the logical mapping is returned in register
R4.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more parameters were in error */
/* H_RESCINDED: A specified parameter refers to a rescinded */
/* shared logical resource */
/* H_Hardware: Operation failed because of hardware error*/
hcall ( const uint64 H_ACCEPT_LOGICAL, /* Returns in R4 handle of a shared logical */
/* resource */
uint64 cookie /* Cookie representing the shared resource */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>cookie: The handle returned by H_GRANT_LOGICAL representing the
logical resource to be accepted.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Verify that the cookie parameter is valid for the calling
partition, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the cookie represents a logical resources that has been
rescinded by the owner, return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Map the resources represented by the cookie parameter, with any
attendant access restrictions, into the lowest available logical address
of the calling partition consistent with constraints of size and
alignment and place the selected logical address into R4.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_58491">
<title>H_RETURN_LOGICAL</title>
<para>The H_RETURN_LOGICAL hcall() unmaps the logical resource from the
client partition&#8217;s logical address space. Prior to calling
H_RETURN_LOGICAL the client partition should have destroyed all virtual
mappings to the section of the logical address space to which the logical
resource is mapped. That is unmapping virtual addresses for MMIO and
System Memory space, invalidating TCEs mapping a shared DMA window pane,
disabling/masking shared interrupt sources and/or inter processor
interrupts. Failing to do so, may result in parameter errors for other
hcall()s and H_Resource from the H_RETURN_LOGICAL hcall(). Part of the
semantic of this call is to determine that no such active mapping exists.
Implementations may be able to determine this quickly if they for example
maintain map counts for various logical resources, if an implementation
searches a significant amount of platform tables, then the hcall() may
return H_Busy and maintain internal state to continue the scan on
subsequent calls using the same cookie parameter. The cookie parameter
remains valid for the calling client partition until the server partition
successfully executes the H_RESCIND_LOGICAL hcall().</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Busy: The operation is not yet complete call again */
/* H_Hardware: Operation failed because of hardware error*/
/* H_Parameter: One or more parameters were in error */
/* H_Resource: The operation failed because resource is in */
/* use by the sharer */
hcall ( const uint64 H_RETURN_LOGICAL, /* Removes the logical resource from the */
/* partition’s logical address map */
uint64 cookie /* Cookie representing the shared resource */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>cookie: The handle returned by H_GRANT_LOGICAL representing the
logical resource to be returned.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Verify that the cookie parameter references an outstanding
instance of a shared logical resource accepted by the calling partition,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Remove the referenced logical resource from the calling
partition&#8217;s logical address map.</para>
</listitem>
<listitem>
<para>Verify that no virtual to logical mappings exist for the
referenced resource, else return H_Resource.</para>
<itemizedlist>
<listitem>
<para>This operation may require extensive processing -- in some cases
the hcall may return H_Busy to allow for improved system responsiveness
-- in these cases the state of the mapping scan is retained in the
hypervisor&#8217;s state structures such that after some number of
repeated calls the function is expected to finish.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="dbdoclet.50569348_33176">
<title>H_VIOCTL</title>
<para>The H_VIOCTL hypervisor call allows the partition to manipulate or
query certain virtual IOA behaviors.</para>
<section>
<title>Command Overview</title>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more parameters were invalid */
/* H_Constrained: The operation failed because of a resource */
/* constraint */
/* H_Hardware: The operation failed because of a hardware */
/* error */
/* H_Not_Found: Subfunction parameter value not supported */
/* H_Closed: The virtual I/O connection is closed */
hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
uint64 unit-address, /* As specified in the virtual IOA device tree node */
uint64 subfunction, /* The subfunction is encoded below */
uint64 parm-1, /* The last three parameters are defined in the semantics */
uint64 parm-2, /* for the specific subfunction. All unused parameters must */
uint64 parm-3 /* be set to zero */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: As specified.</para>
</listitem>
<listitem>
<para>subfunction: Specific subfunction to perform; see
<xref linkend="dbdoclet.50569348_61979" />.</para>
</listitem>
<listitem>
<para>parm-1: Specified in subfunction semantics.</para>
</listitem>
<listitem>
<para>parm-2: Specified in subfunction semantics.</para>
</listitem>
<listitem>
<para>parm-3: Specified in subfunction semantics.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that the subfunction is implemented, else return
H_Not_Found.</para>
</listitem>
<listitem>
<para>Validate the unit-address, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the subfunction is valid for the given virtual IOA, else
return H_Parameter.</para>
</listitem>
<listitem>
<para>Refer to
<xref linkend="dbdoclet.50569348_61979" /> to determine the semantics for
the given subfunction.</para>
</listitem>
</itemizedlist>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_61979">
<title>Semantics for H_VIOCTL subfunction parameter values</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="30*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="35*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Subfunction Number</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Subfunction Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Semantics Defined in</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>(Reserved)</para>
</entry>
<entry>
<para>(Reserved)</para>
</entry>
<entry>
<para>(Reserved)</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>GET_VIOA_DUMP_SIZE</para>
</entry>
<entry morerows="1">
<para>For all VIO options</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_21458" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>GET_VIOA_DUMP</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_46913" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>GET_ILLAN_NUMBER_VLAN_IDS</para>
</entry>
<entry morerows="1">
<para>For the ILLAN option</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_89939" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>GET_ILLAN_VLAN_ID_LIST</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_11481" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x5</para>
</entry>
<entry>
<para>GET_ILLAN_SWITCH_ID</para>
</entry>
<entry>
<para>For the ILLAN option</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_96420" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>DISABLE_MIGRATION</para>
</entry>
<entry morerows="2">
<para>For all vscsi-server and vfc-server</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_45199" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x7</para>
</entry>
<entry>
<para>ENABLE_MIGRATION</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_36839" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry>
<para>GET_PARTNER_INFO</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_51141" />.</para>
</entry>
</row>
<row>
<entry>
<para>0x9</para>
</entry>
<entry>
<para>GET_PARTNER_WWPN_LIST</para>
</entry>
<entry>
<para>For all vfc-server</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_25490" />.</para>
</entry>
</row>
<row>
<entry>
<para>0xA</para>
</entry>
<entry>
<para>DISABLE_ALL_VIO_INTERRUPTS</para>
</entry>
<entry morerows="2">
<para>For the Subordinate CRQ Transport option</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_56284" />
</para>
</entry>
</row>
<row>
<entry>
<para>0xB</para>
</entry>
<entry>
<para>DISABLE_VIO_INTERRUPT</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_22810" />
</para>
</entry>
</row>
<row>
<entry>
<para>0xC</para>
</entry>
<entry>
<para>ENABLE_VIO_INTERRUPT</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_68387" />
</para>
</entry>
</row>
<row>
<entry>
<para>0xD</para>
</entry>
<entry>
<para>GET_ILLAN_MAX_VLAN_PRIORITY</para>
</entry>
<entry>
<para>No</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_18492" />
</para>
</entry>
</row>
<row>
<entry>
<para>0xE</para>
</entry>
<entry>
<para>GET_ILLAN_NUMBER_MAC_ACLS</para>
</entry>
<entry>
<para>No</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_78533" />
</para>
</entry>
</row>
<row>
<entry>
<para>0xF</para>
</entry>
<entry>
<para>GET_MAC_ACLS</para>
</entry>
<entry>
<para>No</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_76359" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x10</para>
</entry>
<entry>
<para>GET_PARTNER_UUID</para>
</entry>
<entry>
<para>For UUID Option</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_62564" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x11</para>
</entry>
<entry>
<para>FW_RESET</para>
</entry>
<entry>
<para>For the VNIC option.</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_96847" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x12</para>
</entry>
<entry>
<para>Get_ILLAN_SWITCHING_MODE</para>
</entry>
<entry>
<para>For any ILLAN adapter with the
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis> property</para>
</entry>
<entry>
<para>
<xref linkend="sec_get_illan_switch" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x13</para>
</entry>
<entry>
<para>DISABLE_INACTIVE_TRUNK<?linebreak?>_RECEPTION</para>
</entry>
<entry>
<para>For any ILLAN adapter with the
<emphasis role="bold"><literal>"ibm,trunk-adapter"</literal></emphasis> property</para>
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569348_29651" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x14</para>
</entry>
<entry>
<para>GET_MAX_REDIRECTED<?linebreak?>_MAPPINGS</para>
</entry>
<entry>
<para>For platforms that support more than a single Redirected RDMA
mapping per virtual TCE.</para>
</entry>
<entry>
<para>
<xref linkend="sec_max_redirected_mappings" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x18</para>
</entry>
<entry>
<para>VNIC_SERVER_STATUS</para>
</entry>
<entry>
<para>For VNIC servers</para>
</entry>
<entry>
<para>
<xref linkend="sec_vnic_server_status" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x19</para>
</entry>
<entry>
<para>GET_SESSION_TOKEN</para>
</entry>
<entry>
<para>For VNIC clients</para>
</entry>
<entry>
<para>
<xref linkend="sec_get_session_token" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1A</para>
</entry>
<entry>
<para>SESSION_ERROR_DETECTED</para>
</entry>
<entry>
<para>For VNIC clients</para>
</entry>
<entry>
<para>
<xref linkend="sec_session_error_detected" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1B</para>
</entry>
<entry>
<para>GET_VNIC_SERVER_INFO</para>
</entry>
<entry>
<para>For VNIC servers</para>
</entry>
<entry>
<para>
<xref linkend="sec_get_vnic_server_info" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1C</para>
</entry>
<entry>
<para>ILLAN_MAC_SCAN</para>
</entry>
<entry>
<para>For any ILLAN adapter with the
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis>
property</para>
</entry>
<entry>
<para>
<xref linkend="sec_illan_mac_scan" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1D</para>
</entry>
<entry>
<para>ENABLE_PREPARE_FOR<?linebreak?>_SUSPEND</para>
</entry>
<entry>
<para>For all vscsi-server and vfc-server</para>
</entry>
<entry>
<para>
<xref linkend="sec_enable_prepare_for_suspend" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1E</para>
</entry>
<entry>
<para>READY_FOR_SUSPEND</para>
</entry>
<entry>
<para>For all vscsi-server and vfc-server</para>
</entry>
<entry>
<para>
<xref linkend="sec_ready_for_suspend" />
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_21458">
<title>GET_VIOA_DUMP_SIZE Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor calculates the size necessary for passing opaque
firmware data describing current virtual IOA state to the partition for
purposes of error logging and RAS, and returns H_Success, with the
required size in R4.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_46913">
<title>GET_VIOA_DUMP Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>If the given virtual IOA has an
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property in its
device tree, then parm-1 is an eight byte output descriptor. The high
order byte of an output descriptor is control, the next three bytes are a
length field of the buffer in bytes, and the low order four bytes are a
TCE mapped I/O address of the start of a buffer in I/O address space. The
high order control byte must be set to zero. The TCE mapped I/O address
is mapped via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>If the given virtual IOA has no
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property in its
device tree, then parm-1 shall be a logical real, page-aligned address of
a 4 K page used to return the virtual IOA dump.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>If parm-1 is an output descriptor, then</para>
<itemizedlist>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Transfer as much opaque hypervisor data as fits into the output
buffer as specified by the output descriptor.</para>
</listitem>
<listitem>
<para>If all opaque data will not fit due to size, return
H_Constrained, else return H_Success.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If parm-1 is a logical real address, then</para>
<itemizedlist>
<listitem>
<para>Validate the logical real address is valid for the partition,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Transfer as much opaque hypervisor data as will fit into the
passed logical real page, with a maximum of 4 K.</para>
</listitem>
<listitem>
<para>If all opaque data will not fit in the page due to size, return
H_Constrained, else return H_Success.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_89939">
<title>GET_ILLAN_NUMBER_VLAN_IDS Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor returns H_Success, with the number of VLAN IDs
(PVID + VIDs) in R4. This subfunction allows the partition to allocate
the correct amount of space for the call:
H_VIOCTL(GET_VLAN_ID_LIST).</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_11481">
<title>GET_ILLAN_VLAN_ID_LIST Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>parm-1 is an eight byte output descriptor. The high order byte of
an output descriptor is control, the next three bytes are a length field
of the buffer in bytes, and the low order four bytes are a TCE mapped I/O
address of the start of a buffer in I/O address space. The high order
control byte must be set to zero. The TCE mapped I/O address is mapped
via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Transfer the VLAN_ID_LIST into the output buffer as specified by
the output descriptor. The data will be an array of two byte values,
where the first element of the array is the PVID followed by all the
VIDs. The format of the elements of the array is specified by IEEE VLAN
documentation. Any unused space in the output buffer will be
zeroed.</para>
</listitem>
<listitem>
<para>If all VLAN IDs do not fit due to size, return
H_Constrained.</para>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_96420">
<title>GET_ILLAN_SWITCH_ID Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>parm-1 is an eight byte output descriptor. The high order byte of
an output descriptor is control, the next three bytes are a length field
of the buffer in bytes, and the low order four bytes are a TCE mapped I/O
address of the start of a buffer in I/O address space. The high order
control byte must be set to zero. The TCE mapped I/O address is mapped
via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Transfer the GET_ILLAN_SWITCH_ID into the output buffer as
specified by the output descriptor. The data will be a string of ASCII
characters uniquely identifying the virtual switch to which the ILLAN
adapter is connected. Any unused space in the output buffer will be
zeroed.</para>
</listitem>
<listitem>
<para>If the switch identifier does not fit due to size, return
H_Constrained.</para>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_45199">
<title>DISABLE_MIGRATION Subfunction Semantics</title>
<para>When this subfunction is implemented, the
<emphasis role="bold"><literal>&#8220;ibm,migration-control&#8221;</literal></emphasis> property exists
in the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> OF device tree node.</para>
<itemizedlist>
<listitem>
<para>Validate that parm-1, parm-2, and parm-3 are all set to zero,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>If no partner is connected, then return H_Closed.</para>
</listitem>
<listitem>
<para>Prevent the migration of the partner partition to the destination
server until either the ENABLE_MIGRATION subfunction is called or
H_FREE_CRQ is called.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_36839">
<title>ENABLE_MIGRATION Subfunction Semantics</title>
<para>When this subfunction is implemented, the
<emphasis role="bold"><literal>&#8220;ibm,migration-control&#8221;</literal></emphasis> property exists
in the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> OF device tree node.</para>
<itemizedlist>
<listitem>
<para>Validate that parm-1, parm-2, and parm-3 are all set to zero,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the migration of the partner partition to the
destination server was previously prevented with DISABLE_MIGRATION
subfunction, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Enable the migration of the partner partition.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_51141">
<title>GET_PARTNER_INFO Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Parm-1 is an eight byte output descriptor. The high order byte of
an output descriptor is control, the next three bytes are a length field
of the buffer in bytes, and the low order four bytes are a TCE mapped I/O
address of the start of a buffer in I/O address space. The high order
control byte must be set to zero. The TCE mapped I/O address is mapped
via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>If the output buffer is not large enough to fit all the data,
then return H_Constrained.</para>
</listitem>
<listitem>
<para>If no partner is connected and more than one possible partner
exists, then return H_Closed.</para>
</listitem>
<listitem>
<para>Transfer the eight byte partner partition ID into the first eight
bytes of the output buffer.</para>
</listitem>
<listitem>
<para>Transfer the eight byte unit address into the second eight bytes
of the output buffer.</para>
</listitem>
<listitem>
<para>Transfer the NULL-terminated Converged Location Code associated
with the partner unit address and partner partition ID immediately
following the unit address.</para>
</listitem>
<listitem>
<para>Zero any remaining output buffer.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_25490">
<title>GET_PARTNER_WWPN_LIST Subfunction Semantics</title>
<para>This subfunction is used to get the WWPNs for the partner from the
hypervisor. In this way, there is assurance that the WWPNs are
accurate.</para>
<itemizedlist>
<listitem>
<para>Parm-1 is an eight byte output descriptor. The high order byte of
an output descriptor is control, the next three bytes are a length field
of the buffer in bytes, and the low order four bytes are a TCE mapped I/O
address of the start of a buffer in I/O address space. The high order
control byte must be set to zero. The TCE mapped I/O address is mapped
via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>If the output buffer is not large enough to fit all the data,
return H_Constrained.</para>
</listitem>
<listitem>
<para>If no partner is connected, return H_Closed.</para>
</listitem>
<listitem>
<para>Transfer the first eight byte WWPN, which is represented in the
<emphasis role="bold"><literal>vfc-client</literal></emphasis> node of the partner partition in the
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-1&#8221;</literal></emphasis> parameter, into the
first eight bytes of the output buffer.</para>
</listitem>
<listitem>
<para>Transfer the second eight byte WWPN, which is represented in the
<emphasis role="bold"><literal>vfc-client</literal></emphasis> node of the partner partition in the
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-2&#8221;</literal></emphasis> parameter, into the
second eight bytes of the output buffer.</para>
</listitem>
<listitem>
<para>Zero any remaining output buffer.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_56284">
<title>DISABLE_ALL_VIO_INTERRUPTS Subfunction
Semantics</title>
<para>This subfunction is used to disable any and all the CRQ and Sub-CRQ
interrupts associated with the virtual IOA designated by the
unit-address, for VIOs that define the use of Sub-CRQs. Software that
controls a virtual IOA that does not define the use of Sub-CRQ facilities
should use the H_VIO_SIGNAL hcall() to disable CRQ interrupts.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this subfunction might change, and the caller should be prepared to
receive an H_Not_Found return code indicating the platform does not
implement this subfunction.</para>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Disable all CRQ and any Sub-CRQ interrupts associated with
unit-address.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_22810">
<title>DISABLE_VIO_INTERRUPT Subfunction Semantics</title>
<para>This subfunction is used to disable a CRQ or Sub-CRQ interrupt, for
VIOs that define the use of Sub-CRQs. The CRQ or Sub-CRQ is defined by
the unit-address and parm-1. Software that controls a virtual IOA that
does not define the use of Sub-CRQ facilities should use the H_VIO_SIGNAL
hcall() to disable CRQ interrupts.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this subfunction might change, and the caller should be prepared to
receive an H_Not_Found return code indicating the platform does not
implement this subfunction.</para>
<itemizedlist>
<listitem>
<para>Parm-1 is the interrupt number of the interrupt to be disabled.
For an interrupt associated with a CRQ this number is obtained from the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property in the device tree
For an interrupt associated with a Sub-CRQ this number is obtained during
the registration of the Sub-CRQ (H_REG_SUB_CRQ).</para>
</listitem>
<listitem>
<para>Validate parm-1 is a valid interrupt number for a CRQ or Sub-CRQ
for the virtual IOA defined by parm-1 and that parm-2 and parm-3 are set
to zero, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Disable interrupt specified by parm-1.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_68387">
<title>ENABLE_VIO_INTERRUPT Subfunction Semantics</title>
<para>This subfunction is used to enable a CRQ or Sub-CRQ interrupt, for
VIOs that define the use of Sub-CRQs. The CRQ or Sub-CRQ is defined by
the unit-address and parm-1. Software that controls a virtual IOA that
does not define the use of Sub-CRQ facilities should use the H_VIO_SIGNAL
hcall() to disable CRQ interrupts.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this subfunction might change, and the caller should be prepared to
receive an H_Not_Found return code indicating the platform does not
implement this subfunction.</para>
<itemizedlist>
<listitem>
<para>Parm-1 is the interrupt number of the interrupt to be enabled.
For an interrupt associated with a CRQ this number is obtained from the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property in the device tree
For an interrupt associated with a Sub-CRQ this number is obtained during
the registration of the Sub-CRQ (H_REG_SUB_CRQ).</para>
</listitem>
<listitem>
<para>Validate parm-1 is a valid interrupt number for a CRQ or Sub-CRQ
for the virtual IOA defined by unit-address and that parm-2 and parm-3
are set to zero, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Enable interrupt specified by parm-1.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_18492">
<title>GET_ILLAN_MAX_VLAN_PRIORITY Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor returns H_Success, with the maximum IEEE 802.1Q
VLAN priority returned in R4. If no priority limits are in place, the
maximum VLAN priority is returned in R4.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_78533">
<title>GET_ILLAN_NUMBER_MAC_ACLS Subfunction Semantics</title>
<para>This subfunction allows the partition to allocate the correct
amount of space for the GET_MAC_ACLS Subfunction call.</para>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor returns H_Success, with the number of allowed MAC
addresses returned in R4. If no MAC access control limits are in place, 0
is returned in R4.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_76359">
<title>GET_MAC_ACLS Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>parm-1 is an eight byte output descriptor. The high order byte of
an output descriptor is control, the next three bytes are a length field
of the buffer in bytes, and the low order four bytes are a TCE mapped I/O
address of the start of a buffer in I/O address space. The high order
control byte must be set to zero. The TCE mapped I/O address is mapped
via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate the I/O address range is in the required DMA window and
is mapped by valid TCEs, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Transfer the allowed MAC addresses into the output buffer as
specified by the output descriptor. The data will be an array of 8 byte
values containing the allowed MAC address, with the low order 6 bytes
containing the 6 byte MAC address. Any unused space in the output buffer
are zeroed.</para>
</listitem>
<listitem>
<para>If all allowed MAC addresses do not fit due to size, return
H_Constrained.</para>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_62564">
<title>GET_PARTNER_UUID Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2 and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>If no partner is connected and more than one possible partner
exists, then return H_Closed.</para>
</listitem>
<listitem>
<para>Transfer into registers R4 (High order 8 bytes) and R5 (low order
8 bytes) of the UUID of the client partition that owns the virtual device
(
<xref linkend="dbdoclet.50569332_20419" /> for the format of the UUID string.</para>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_96847">
<title>FW_Reset Subfunction Semantics</title>
<para>This H_VIOCTL subfunction will reset the VNIC firmware associated
with a VNIC client adapter, if currently active. This subfunction is
useful when the associated firmware becomes unresponsive to other
CRQ-based commands. For the case of vTPMs the firmware will be left
inoperable until the client partition next boots up.</para>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that parm-1, parm-2, and parm-3 are all set to zero,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>If the firmware associated with the virtual adapter can not be
reset, return H_Constrained.</para>
</listitem>
<listitem>
<para>Reset the firmware associated with the virtual adapter.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="sec_get_illan_switch">
<title>GET_ILLAN_SWITCHING_MODE Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the given virtual IOA is a ILLAN adapter with the
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis>, else return H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor returns H_Success, with the current switching mode
in R4. If the switching mode is VEB mode, R4 will have a 0. If the
switching mode is VEPA mode, R4 will have a 1.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_29651">
<title>DISABLE_INACTIVE_TRUNK_RECEPTION Subfunction
Semantics</title>
<para>This subfunction is used to disable the reception of all packets
for a ILLAN trunk adapter that is not the Active Trunk Adapter as set by
the H_ILLAN_ATTRIBUTES hcall.</para>
<para>
<emphasis role="bold">Note:</emphasis> The default value for this attribute is
ENABLED. The value is reset on a successful H_FREE_LOGICAL_LAN hcall or
reboot/power change of the partition owning the ILLAN adapter.</para>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the given virtual IOA is a ILLAN adapter with the
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis>, else return H_Parameter.</para>
</listitem>
<listitem>
<para>The hypervisor disables reception of packets for this adapter
when it is not the Active Trunk Adapter.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_max_redirected_mappings">
<title>GET_MAX_REDIRECTED_MAPPINGS Subfunction
Semantics</title>
<para>This sub-function retrieves the maximum number of additional
redirected mappings for the specified adapter.</para>
<itemizedlist>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else return
H_Parameter</para>
</listitem>
<listitem>
<para>Validate that the given virtual IOA is an RDMA-capable server adapter,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Store the maximum number of additional redirected mappings for
the LIOBN in R4.</para>
</listitem>
<listitem>
<para>Store the maximum number of redirections per client IOBA in R5.</para>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_vnic_server_status">
<title>VNIC_SERVER_STATUS Subfunction Semantics</title>
<para>This subfunction is used to report the status of the physical
backing device corresponding to a specific VNIC server adapter.
Additionally, this subfunction is used as a heartbeat mechanism
that the hypervisor utilizes to ensure the backing device associated
with the virtual adapter is responsive.</para>
<itemizedlist>
<listitem>
<para>parm-1 is an enumerated value reflecting the physical backing
evice status. Validate that parm-1 is one of the following values:
0x1 (Operational), 0x2 (LinkDown), or 0x3 (AdapterError). Otherwise,
return H_Parameter.</para>
</listitem>
<listitem>
<para>parm-2 is a value, in milliseconds, that the caller utilizes
to specify how long the hypervisor should wait for the next server
status vioctl call.</para>
</listitem>
<listitem>
<para>Validate that parm-3 is zero, else return H_Parameter.</para>
</listitem>
<listitem>
<para>If the CRQ for the server adapter has not yet been registered,
return H_State.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_get_session_token">
<title>GET_SESSION_TOKEN Subfunction Semantics</title>
<para>This subfunction is used to obtain a session token from a VNIC client adapter.
This token is opaque to the caller and is intended to be used in tandem with the
SESSION_ERROR_DETECTED vioctl subfunction.</para>
<note><para>On platforms that implement the partition migration option, after partition
migration the support for this subfunction might change, and the caller
should be prepared to receive an H_Not_Found return code indicating the platform
does not implement this subfunction.</para></note>
<itemizedlist>
<listitem>
<para>Validate that parm-1, parm-2, and parm-3 are 0, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Return H_Success, with the session token in R4.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_session_error_detected">
<title>SESSION_ERROR_DETECTED Subfunction Semantics</title>
<para>This subfunction is used to report that the currently active
backing device for a VNIC client adapter is behaving poorly, and
that the hypervisor should attempt to fail over to a different backing
device, if one is available.</para>
<note><para>On platforms that implement the partition migration option,
after partition migration the support for this subfunction might change,
nd the caller should be prepared to receive an H_Not_Found return code
indicating the platform does not implement this subfunction.</para></note>
<itemizedlist>
<listitem>
<para>parm-1 is a VNIC session token. This token should be obtained
from the GET_SESSION_TOKEN vioctl subfunction.</para>
</listitem>
<listitem>
<para>Validate that parm-2 and parm-3 are 0, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the session token parameter corresponds to the current
VNIC session, else return H_State.</para>
</listitem>
<listitem>
<para>Validate that the active server status is Operational, else return
H_Constrained.</para>
</listitem>
<listitem>
<para>If the server status is Operational, change the server status to
NetworkError and attempt to fail over to a different backing device.
If there are no suitable servers to fail over to, return H_Constrained.</para>
</listitem>
<listitem>
<para>If the client successfully failed over to another backing device
as a result of this subfunction call, return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_get_vnic_server_info">
<title>GET_VNIC_SERVER_INFO Subfunction Semantics</title>
<para>This subfunction is used to fetch information about a VNIC server
adapter.</para>
<itemizedlist>
<listitem>
<para>parm-1 is an eight byte output descriptor. The high order
byte of an output descriptor is control, the next three bytes are
a length field of the buffer in bytes, and the low order four bytes
are a TCE mapped I/O address of the start of a buffer in I/O address
space. The high order control byte must be set to zero. The TCE mapped
I/O address is mapped via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property.</para>
</listitem>
<listitem>
<para>Validate that parm-2 and parm-3 are 0, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Populate the TCE mapped buffer with the following information.
Note that if the buffer descriptor (parm-1) describes an output buffer
that is not large enough to hold the following information, the server
information will be truncated to the size of the output buffer and the
buffer will be populated with the truncated information.
<informaltable frame="all" pgwide="1">
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="60*" />
<thead>
<row>
<entry>
<para><emphasis role="bold">Field</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Byte Offset</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Size</emphasis></para>
</entry>
<entry align="center">
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>The format version of the provided information.
The first supported version is 1.</para>
</entry>
</row>
<row>
<entry>
<para>Active</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Boolean value describing whether or not this server
adapter is currently the active server for the client
adapter it is mapped to.
<itemizedlist spacing="compact">
<listitem>
<para>0x0 - The server is not currently active.</para>
</listitem>
<listitem>
<para>0x1 - The server is currently the active backing
device for the client.</para>
</listitem>
</itemizedlist>
</para>
</entry>
</row>
<row>
<entry>
<para>Status</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Enumeration value corresponding to the current
virtual adapter status.
<itemizedlist spacing="compact">
<listitem>
<para>0x1 - Operational - The server adapter is working
as expected.</para>
</listitem>
<listitem>
<para>0x2 - LinkDown - The SR-IOV backing device's
physical link is down.</para>
</listitem>
<listitem>
<para>0x3 - AdapterError - SR-IOV adapter is undergoing
EEH.</para>
</listitem>
<listitem>
<para>0x4 - PoweredOff - The virtual server adapter
or its hosting partition is powered off.</para>
</listitem>
<listitem>
<para>0x5 - NetworkError - VNIC client detected a network
issue with this adapter.</para>
</listitem>
<listitem>
<para>0x6 - Unresponsive - The hypervisor is not reliably
receiving VNIC_SERVER_STATUS vioctl calls from the VNIC
server.</para>
</listitem>
</itemizedlist>
</para>
</entry>
</row>
<row>
<entry>
<para>Priority</para>
</entry>
<entry>
<para>24</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>The current priority of this server adapter. Lower
values take precedence over larger values.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>25</para>
</entry>
<entry>
<para>7</para>
</entry>
<entry>
<para>This field is reserved and must be zero.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_illan_mac_scan">
<title>ILLAN_MAC_SCAN Subfunction Semantics</title>
<itemizedlist>
<listitem>
<para>parm-1 is an eight byte output descriptor. The high order
byte of an output descriptor is control, the next three bytes are
a length field of the buffer in bytes, and the low order four bytes
are a TCE mapped I/O address of the start of a buffer in I/O address
space. The high order control byte must be set to zero. The TCE mapped
I/O address is mapped via the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property.</para>
</listitem>
<listitem>
<para>Parm-2 and parm-3 should be set to the opaque continuation tokens
CT1 and CT2, respectively. These values are returned by the hypervisor
through the ILLAN_MAC_SCAN Buffer header when a scan cannot be completed
within a single vioctl call. See
<xref linkend="illan_mac_scan_buffer_format_table" />
for more information about the values CT1 and CT2. Parm-2 and parm-3
should be set to zero when starting a new ILLAN_MAC_SCAN call sequence.</para>
</listitem>
<listitem>
<para>Validate that the unit-address corresponds to an active ILLAN
trunk adapter, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate parm-2 and parm-3 are both set to zero, or contain
valid continuation tokens, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the I/O address range supplied by parm-1 is large
enough to hold the header information for the ILLAN_MAC_SCAN Buffer
detailed in
<xref linkend="illan_mac_scan_buffer_format_table" />,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the I/O address supplied by parm-1 is 8-byte aligned,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>If any data transfers to the I/O address range supplied by parm-1
fail, return H_Permission.</para>
</listitem>
<listitem>
<para>Iterate over all VLAN ids associated with the specified trunk
adapter. For each associated VLAN id:
<itemizedlist>
<listitem>
<para>Iterate over all ILLAN adapters, barring any adapters
with the
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis>
property, belonging to the current VLAN id.</para>
</listitem>
<listitem>
<para>For each non-trunk ILLAN adapter belonging to the current
VLAN id, add a 64-bit value containing the current 12-bit VLAN id
and the 48-bit MAC address of the ILLAN adapter to the next vacant
entry in the MAC/VID Buffer. Each MAC/VID pair in the buffer
is formatted as shown in
<xref linkend="mac_vid_pair_entry_format_table" />
Note that when handling H_IN_PROGRESS return codes, the caller
should either copy information from the buffer, immediately
process the information in the buffer, or modify the output
descriptor to utilize a new, non-overlapping buffer I/O address
range after each call. Otherwise, the buffer data will be overwritten
on consecutive calls.
<table frame="all" pgwide="1" xml:id="mac_vid_pair_entry_format_table">
<?dbhtml table-width="50%" ?><?dbfo table-width="50%" ?>
<title>MAC/VID Pair Entry Format</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="50*" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<thead>
<row>
<entry align="center">
<para><emphasis role="bold">Field</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Bit Offset</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Bit Length</emphasis></para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>RESERVED</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>802.1qVLAND ID</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>12</para>
</entry>
</row>
<row>
<entry>
<para>Adapter MAC Address</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>48</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
<listitem>
<para>If at any point during iteration the vioctl call exceeds
the maximum allotted time interval, or if the MAC/VID buffer
is filled to capacity, do the following:
<itemizedlist>
<listitem>
<para>Store 'CT1' and 'CT2' in the buffer header so the
operation can be continued on the next call</para>
</listitem>
<listitem>
<para>Set 'Num Entries' in the buffer header to the number
of valid MAC/VID pairs in the output buffer</para>
</listitem>
<listitem>
<para>Set 'Reconfiguration Occurred' based on the rules
described in the <emphasis>Dynamic Reconfiguration</emphasis> description item below</para>
</listitem>
<listitem>
<para>Return H_IN_PROGRESS.
<table frame="all" pgwide="1" xml:id="illan_mac_scan_buffer_format_table">
<title>ILLAN_MAC_SCAN Buffer Format</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="10*" align="center" />
<colspec colname="c5" colwidth="40*" />
<thead>
<row>
<entry>
<para></para>
</entry>
<entry>
<para><emphasis role="bold">Field</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Byte Offset</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Byte Length</emphasis></para>
</entry>
<entry align="center">
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="middle" morerows="4">
<para><emphasis role="bold">Header</emphasis></para>
</entry>
<entry>
<para>CT1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Continuation token 1 – this value should be used as
parm-2 for sequential calls to ILLAN_MAC_SCAN when
handling H_IN_PROGRESS return codes</para>
</entry>
</row>
<row>
<entry>
<para>CT2</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Continuation token 2 – this value should be used
as parm-3 for sequential calls to ILLAN_MAC_SCAN when
handling H_IN_PROGRESS return codes.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>15</para>
</entry>
<entry>
<para>This field is reserved and should be set to zero.</para>
</entry>
</row>
<row>
<entry>
<para>Reconfiguration Occurred</para>
</entry>
<entry>
<para>31</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<itemizedlist spacing="compact">
<listitem>
<para>0: The data in this buffer is guaranteed to be
consistent with the virtual adapter configuration at
the point of return</para>
</listitem>
<listitem>
<para>1: The data in this buffer may contain data
inconsistencies due to reconfiguration of
ILLAN adapters between consecutive calls
to ILLAN_MAC_SCAN. See
<emphasis>Dynamic Reconfigurations</emphasis> description below.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Num Entries</para>
</entry>
<entry>
<para>32</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>The number of valid 64-bit MAC/VID pairs in this buffer</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">Data</emphasis></para>
</entry>
<entry>
<para>MAC/VID Buffer Start</para>
</entry>
<entry>
<para>40</para>
</entry>
<entry>
<para>Variable</para>
</entry>
<entry>
<para>A variably-sized, contiguous array of MAC/VID pairs
formatted according to
<xref linkend="mac_vid_pair_entry_format_table" />.
The number of valid entries in this array is
specified by the “Num Entries” field.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>If all MAC addresses were successfully scanned for all VLAN ids on
the trunk adapter, do the following:
<itemizedlist>
<listitem>
<para>Set 'CT1' and 'CT2' to zero in the buffer header</para>
</listitem>
<listitem>
<para>Set 'Num Entries' in the buffer header to the number of
valid MAC/VID pairs in the output buffer</para>
</listitem>
<listitem>
<para>Set 'Reconfiguration Occurred' based on the rules described
in the Dynamic Reconfiguration section below</para>
</listitem>
<listitem>
<para>Return H_SUCCESS.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Note that the buffer headers and data are only valid if this
vioctl returns H_IN_PROGRESS or H_SUCCESS.</para>
</listitem>
<listitem>
<para>Note that any unused buffer space outside of the range determined
by the 'Num Entries' field in the ILLAN_MAC_SCAN buffer header is
undefined by this architecture.</para>
</listitem>
<listitem>
<para><emphasis><emphasis role="bold">Dynamic Reconfigurations:</emphasis></emphasis>
If the 'Reconfiguration Occurred' field in the ILLAN_MAC_SCAN buffer
header is TRUE (1), the data in all MAC/VID buffers in a call sequence
may contain inconsistencies due to dynamic reconfiguration events for
the trunk adapter itself or any ILLAN adapters associated with the
trunk adapter. In this case, all data collected from the call sequence
should be utilized with caution, or re-queried. Possible inconsistencies
arising from dynamic reconfiguration include the following:
<itemizedlist>
<listitem>
<para>MAC addresses in the buffer may correspond to ILLAN adapters
that have been removed from the switch, due to partition suspension,
hibernation, adapter disablement, and DLPAR operations</para>
</listitem>
<listitem>
<para>MAC addresses corresponding to ILLAN adapters that were
added to the virtual switch due to partition resumption,
adapter enablement, and DLPAR operations may not be included
in the buffer</para>
</listitem>
<listitem>
<para>ILLAN adapters may have their VLAN memberships reconfigured,
in which case certain VID/MAC pairs in the buffer may no longer
be valid, and some valid VID/MAC pairs for ILLAN adapters may
not be included in the buffer at all.</para>
</listitem>
<listitem>
<para>ILLAN adapters may have their MAC address reconfigured.
Both the old and new MAC addresses for the adapter may be included
in the buffer, or the old and new MAC addresses for the adapter
may not be included in the buffer at all.</para>
</listitem>
</itemizedlist>
Note that even if the value of the 'Reconfiguration Occurred' field is
FALSE (0), ILLAN adapter reconfigurations may have occurred immediately
after the vioctl completed, and the information in the buffer could be
outdated.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_enable_prepare_for_suspend">
<title>ENABLE_PREPARE_FOR_SUSPEND Subfunction Semantics</title>
<para>This subfunction is used to enable the “Prepare For Suspend”
transport event on a VSCSI or VFC server adapter for which this
function is called. If enabled and when a client partition is
about to be migrated, the “Prepare For Suspend” transport event
will be enqueued on the server's command queue, if active.
The server should then quiesce all I/O to the backing store and
respond when ready by calling the H_VIOCTL READY_FOR_SUSPEND subfunction.
This subfunction should be called after each H_REG_CRQ as H_REG_CRQ will
disable the support. When enabled, a “Resume” transport event will be
enqueued on the server's command queue, if active, when the client
partition resumes regardless of whether it successfully suspended.
<itemizedlist>
<listitem>
<para>Parm-1 is an eight byte timeout value in milliseconds. The
timeout value specifies the maximum amount of time in milliseconds
the Hypervisor should wait after enqueueing the “Prepare for Suspend”
transport event on the server's command queue until receiving the
H_VIOCTL READY_FOR_SUSPEND subfunction from the server. The
timeout value should take into account the maximum amount of
time to queisce I/O operations prior to migration of the client
partition.</para>
</listitem>
<listitem>
<para>Validate that the unit-address corresponds to a VSCSI or VFC
server adapter, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate parm-1 is less than or equal to 30,000 milliseconds,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate parm-2, and parm-3 are set to zero, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Verify the server adapter is not configured for “Any client can connect”,
else return H_Constrained</para>
</listitem>
<listitem>
<para>If this Subfunction parameter value not supported by Hypervisor,
return H_Not_Found.</para>
</listitem>
<listitem>
<para>If “Prepare For Suspend” is successfully enabled, H_Success will
be returned and an opaque Hypervisor version placed in R4</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="sec_ready_for_suspend">
<title>READY_FOR_SUSPEND Subfunction Semantics</title>
<para>This subfunction is used to respond to the “Prepare For Suspend” transport
event on a VSCSI or VFC server adapter for which this function is called. If
enabled via the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, the server
should call this H_VIOCTL READY_FOR_SUSPEND subfunction after receiving the
“Prepare For Suspend” transport event and quiescing I/O operations to the
backing store. If the server is unable to call this subfunction within the
timeout specified in the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction,
the migration operation on the client partition will be aborted.
<itemizedlist>
<listitem>
<para>Validate that the unit-address corresponds to a VSCSI or VFC
server adapter, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate parm-1, parm-2, and parm-3 are set to zero, else
return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the server has previously called the H_VIOCTL
ENABLE_PREPARE_FOR_SUSPEND subfunction after the most recent
H_REG_CRQ, else return H_Constrained.</para>
</listitem>
<listitem>
<para>If this Subfunction parameter value not supported by Hypervisor,
return H_Not_Found.</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569348_94955">
<title>Partition Managed Class Infrastructure - General</title>
<para>In addition to the general requirements for all VIO described in
<xref linkend="dbdoclet.50569348_66872" />, the architecture for the
partition managed class of VIO defines several other
infrastructures:</para>
<itemizedlist>
<listitem>
<para>A Command/Response Queue (CRQ) that allows communications back
and forth between the server partition and its partner partition (see
<xref linkend="dbdoclet.50569348_98947" />).</para>
</listitem>
<listitem>
<para>A Subordinate CRQ (Sub-CRQ) facility that may be used in
conjunction with the CRQ facility, when the CRQ facility by itself is not
sufficient. That is, when more than one queue with more than one
interrupt is required by the virtual IOA. See
<xref linkend="dbdoclet.50569348_92689" />.</para>
</listitem>
<listitem>
<para>A mechanism for doing RDMA, which includes:</para>
<itemizedlist>
<listitem>
<para>A mechanism called Copy RDMA that can be used by the device
driver to move blocks of data between memory of the server and partner
partitions</para>
</listitem>
<listitem>
<para>A mechanism for Redirected RDMA that allows the device driver to
direct DMA of data from the server partition&#8217;s physical IOA to or
from the partner partition&#8217;s memory (see
<xref linkend="dbdoclet.50569348_25634" />).</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>The mechanisms for the synchronous type VIO are described as
follows:</para>
<itemizedlist>
<listitem>
<para><emphasis><xref linkend="dbdoclet.50569348_51946" /></emphasis></para>
</listitem>
</itemizedlist>
<para>&#160;</para>
<section xml:id="dbdoclet.50569348_98947">
<title>Command/Response Queue (CRQ)</title>
<para>The CRQ facility provides ordered delivery of messages between
authorized partitions. The facility is reliable in the sense that the
messages are delivered in sequence, that the sender of a message is
notified if the transport facility is unable to deliver the message to
the receiver&#8217;s queue, and that a notification message is delivered
(providing that there is free space on the receive queue), or if the
partner partition either fails or deregisters its half of the transport
connection. The CRQ facility does not police the contents of the payload
portions (after the 1 byte header) of messages that are exchanged between
the communicating pairs, however, this architecture does provide means
(via the Format Byte) for self describing messages such that the
definitions of the content and protocol between using pairs may evolve
over time without change to the CRQ architecture, or its
implementation.</para>
<para>The CRQ is used to hold received messages from the partner
partition. The CRQ owner may optionally choose to be notified via an
interrupt when a message is added to their queue.</para>
<section xml:id="dbdoclet.50569348_27166">
<title>CRQ Format and Registration</title>
<para>The CRQ is built of one or more 4 KB pages aligned on a 4 KB
boundary within partition memory. The queue is organized as a circular
buffer of 16 byte long elements. The queue is mapped into contiguous I/O
addresses via the TCE mechanism and RTCE table (first window pane). The
I/O address and length of the queue are registered by
<xref linkend="dbdoclet.50569348_13013" />. This registration process
tells the hypervisor where to find the virtual IOA&#8217;s CRQ.</para>
</section>
<section xml:id="dbdoclet.50569348_54982">
<title>CRQ Entry Format</title>
<para>Each CRQ entry consists of a 16 byte element. The first byte of a
CRQ entry is the Header byte and is defined in
<xref linkend="dbdoclet.50569348_49382" />.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_49382">
<title>CRQ Entry Header Byte Values</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Header Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Element is unused -- all other bytes in the element are
undefined</para>
</entry>
</row>
<row>
<entry>
<para>0x01 - 0x7F</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Command/Response entry -- the second byte defines
the entry format (for example, see
<xref linkend="dbdoclet.50569351_41722" />).</para>
</entry>
</row>
<row>
<entry>
<para>0x81 - 0xBF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0xC0</para>
</entry>
<entry>
<para>Valid Initialization Command/Response entry -- the second
byte defines the entry format. See
<xref linkend="dbdoclet.50569348_18170" />.</para>
</entry>
</row>
<row>
<entry>
<para>0xC1 - 0xFE</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>Valid Transport Event -- the second byte defines the
specific transport event. See
<xref linkend="dbdoclet.50569348_93265" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The platform (transport mechanism) ignores the contents of all
non-header bytes in all CRQ entries.</para>
<para>Valid Command/Response entries (Header byte 0x80) are used to carry
data between communicating partners, transparently to the platform. The
second byte of the entry is reserved for a Format byte to enable the
definitions of the content and protocol between using pairs to evolve
over time. The definition of the second byte of the Valid
Command/Response entry is beyond the scope of this architecture.
<xref linkend="dbdoclet.50569351_41722" /> presents example VSCSI format
byte values.</para>
<para>The Valid Initialization Command/Response entry (Header byte 0xC0)
is used during virtual IOA initialization sequences. The second byte of
this type entry is architected and is as defined in
<xref linkend="dbdoclet.50569348_18170" />. This format is used for
initialization operations between communicating partitions. The remaining
bytes (byte three and beyond) of the Valid Initialization
Command/Response entry are available for definition by the communicating
entities.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_18170">
<title>Initialization Command/Response Entry Format Byte
Definitions</title>
<?dbhtml table-width="50%" ?><?dbfo table-width="50%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Format Byte Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Initialize</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Initialization Complete</para>
</entry>
</row>
<row>
<entry>
<para>0x03 - 0xFE</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Valid Transport Events (Header byte 0xFF) are used by the platform
to notify communicating partners of conditions associated with the
transport channel, such as the failure of the partner&#8217;s partition
or the deregistration of the partner&#8217;s queue. The partner&#8217;s
queue may be deregistered as a means of resetting the transport channel
or simply to terminate the connection. When the Header byte of the queue
entry specifies a Valid Transport Event, then the second byte of the CRQ
entry defines the type of transport event. The Format byte (second byte)
of a Valid Transport Event queue entry is architected and is as defined
in
<xref linkend="dbdoclet.50569348_93265" />).</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_93265">
<title>Transport Event Codes</title>
<?dbhtml table-width="50%" ?><?dbfo table-width="50%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Code Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Explanation</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Partner partition failed</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Partner partition deregistered CRQ</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>Partner partition suspended (for the Partition Suspension
option)</para>
</entry>
</row>
<row>
<entry>
<para>0x07 - 0x08</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x09</para>
</entry>
<entry>
<para>Prepare for Client Adapter Suspend<?linebreak?>
See <xref linkend="sec_enable_prepare_for_suspend"/></para>
</entry>
</row>
<row>
<entry>
<para>0x0A</para>
</entry>
<entry>
<para>Client Adapter Resume<?linebreak?>
See <xref linkend="sec_ready_for_suspend"/></para>
</entry>
</row>
<row>
<entry>
<para>0x0B - 0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The &#8220;partner partition suspended&#8221; transport event
disables the associated CRQ such that any H_SEND_CRQ hcall() (
<xref linkend="dbdoclet.50569348_67318" />) to the associated CRQ returns
H_Closed until the CRQ has been explicitly enabled using the H_ENABLE_CRQ
hcall (See
<xref linkend="dbdoclet.50569348_43427" />).</para>
</section>
<section>
<title>CRQ Entry Processing</title>
<para>Prior to the partition software registering the CRQ, the partition
software sets all the header bytes to zero (entry invalid). After
registration, the first valid entry is placed in the first element and
the process proceeds to the end of the queue and then wraps around to the
first entry again (given that the entry has been subsequently marked as
invalid). This allows both the partition software and transport firmware
to maintain independent pointers to the next element they will be
respectively using.</para>
<para>A sender uses an infrastructure dependent method to enter a 16 byte
message on its partner&#8217;s queue (see
<xref linkend="dbdoclet.50569348_99091" />). Prior to enqueueing an entry
on the CRQ, the platform first checks if the session to the
partner&#8217;s queue is open, and there is a free entry, if not, it
returns an error. If the checks succeed, the contents of the message is
copied into the next free queue element, potentially notifying the
receiver, and returns a successful status to the caller.</para>
<para>At the receiver&#8217;s option, it may be notified via an interrupt
when an element is enqueued to its CRQ. See
<xref linkend="dbdoclet.50569348_58779" />.</para>
<para>When the receiver has finished processing a queue entry, it writes
the header to the value 0x00 to invalidate the entry and free it for
future entries.</para>
<para>Should the receiver wish to terminate or reset the communication
channel it deregisters the queue, and if it needs to re-establish
communications, proceeds to register either the same or different section
of memory as the new queue, with the queue pointers reset to the first
entry.</para>
</section>
<section xml:id="dbdoclet.50569348_58779">
<title>CRQ Facility Interrupt Notification</title>
<para>The receiver can set the virtual interrupt associated with its CRQ
to one of two modes. These are:</para>
<orderedlist>
<listitem>
<para>Disabled (An enqueue interrupt is not signaled.)</para>
</listitem>
<listitem>
<para>Enabled (An enqueue interrupt is signaled on every
enqueue)</para>
</listitem>
</orderedlist>
<para><emphasis role="bold">Note:</emphasis> An enqueue is considered a pulse not a level.
The pulse then sets the memory element within the emulated interrupt
source controller. This allows the resetting of the interrupt condition
by simply issuing the H_EOI hcall() as is done with the PCI MSI
architecture rather than having to do an explicit interrupt reset as in
the case with PCI Level Sensitive Interrupt (LSI) architecture.</para>
<para>The interrupt mechanism is capable of presenting only one interrupt
signal at a time from any given interrupt source. Therefore, no
additional interrupts from a given source are ever signaled until the
previous interrupt has been processed through to the issuance of an H_EOI
hcall(). Specifically, even if the interrupt mode is enabled, the effect
is to interrupt on an empty to non-empty transition of the queue.
However, as with any asynchronous posting operation race conditions are
to be expected. That is, an enqueue can happen in a window around the
H_EOI hcall(). Therefore, the receiver should poll the CRQ after an H_EOI
to prevent losing initiative.</para>
<para>See <emphasis><xref linkend="dbdoclet.50569348_27549" /></emphasis>) for
information about interrupt control.</para>
</section>
<section>
<title>Extensions to Other hcall()s for CRQ</title>
<para />
<section xml:id="dbdoclet.50569348_79056">
<title>H_MIGRATE_DMA</title>
<para>Since the CRQ is RTCE table mapped, the H_MIGRATE_DMA hcall() may
be requested to move a page that is part of the CRQ. The OS owner of the
queue is responsible for preventing its processors from modifying the
page during the migrate operation (as is standard practice with this
hcall()), however, the H_MIGRATE_DMA hcall() serializes with the CRQ
hcall()s to direct new elements to the migrated target page.</para>
</section>
<section xml:id="dbdoclet.50569348_13729">
<title>H_XIRR, H_EOI</title>
<para>The CRQ facility utilizes a virtual interrupt source number to
notify the queue owner of new element enqueues. The standard H_XIRR and
H_EOI hcall()s are extended to support this virtual interrupt mechanism,
emulating the standard PowerPC Interrupt hardware with respect to the
virtual interrupt source number.</para>
</section>
</section>
<section xml:id="dbdoclet.50569348_69369">
<title>CRQ Facility Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must implement the
CRQ as specified in
<xref linkend="dbdoclet.50569348_98947" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must reject CRQ
definitions that are not 4 KB aligned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must reject CRQ
definitions that are not a multiple of 4 KB long.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must reject CRQ
definitions that are not mapped relative to the TCE mapping defined by
the first window pane of the virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_60553">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis>
The platform must
start enqueueing Commands/Responses to the newly registered CRQ starting
at offset zero and proceeding as in a circular buffer, each entry being
16 byte aligned.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_53452">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis>
The platform must
enqueue Commands/Responses only if the 16 byte entry is free (header byte
contains 0x00), else the enqueue operation fails.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must enqueue the
16 bytes specified in the validated enqueue request as specified in
Requirement
<xref linkend="dbdoclet.50569348_60553" />except as required by
Requirement
<xref linkend="dbdoclet.50569348_53452" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_88029">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis>
The platform must
not enqueue commands/response entries if the CRQ has not been registered
successfully or if after a successful completion, has subsequently
deregistered the CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform (transport
mechanism) must ignore and must not modify the contents of all non-header
bytes in all CRQ entries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The first byte of a CRQ entry
must be the Header byte and must be as defined in
<xref linkend="dbdoclet.50569348_49382" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The Format byte (second byte)
of a Valid Initialization CRQ entry must be as defined in
<xref linkend="dbdoclet.50569348_18170" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The Format byte (second byte)
of a Valid Transport Event queue entry must be as defined in
<xref linkend="dbdoclet.50569348_93265" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> If the partner partition fails,
then the platform must enqueue a 16 byte entry starting with 0xFF01 (last
14 bytes unspecified) as specified in Requirement
<xref linkend="dbdoclet.50569348_60553" /> except as required by
Requirements
<xref linkend="dbdoclet.50569348_53452" /> and
<xref linkend="dbdoclet.50569348_88029" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> If the partner partition
deregisters its corresponding CRQ, then the platform must enqueue a 16
byte entry starting with 0xFF02 (last 14 bytes unspecified) as specified
in Requirement
<xref linkend="dbdoclet.50569348_60553" /> except as required by
Requirements
<xref linkend="dbdoclet.50569348_53452" /> and
<xref linkend="dbdoclet.50569348_88029" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<!-- FIXME: Is this placeholder needed? >
<para>R1-17.2.2.1.6-15.
</para-->
<para>Reserved</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility with the Partner Control
option:</emphasis> If the partner partition is terminated by request of
this partition via the
<emphasis>ibm,partner-control</emphasis> RTAS call, then the platform must
enqueue a 16 byte entry starting with 0xFF04 (last 14 bytes unspecified)
as specified in Requirement
<xref linkend="dbdoclet.50569348_60553" /> except as required by
Requirements
<xref linkend="dbdoclet.50569348_53452" /> and
<xref linkend="dbdoclet.50569348_88029" /> when the partner partition has
been successfully terminated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<!-- FIXME: Is this placeholder needed? >
<para>R1-17.2.2.1.6-17.
</para-->
<para>Reserved</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility option:</emphasis> Platforms that implement
the H_MIGRATE_DMA hcall() must implement that function for pages mapped
for use by the CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platforms must emulate the
standard PowerPC External Interrupt Architecture for the interrupt source
numbers associated with the virtual devices via the standard RTAS and
hypervisor interrupt calls and must extend H_XIRR and H_EOI hcall()s as
appropriate for CRQ interrupts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform&#8217;s OF must
disable interrupts from the using virtual IOA before initially passing
control to the booted partition program.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-21.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform&#8217;s OF must
disable interrupts from the using virtual IOA upon registering the
IOA&#8217;s CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-22.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform&#8217;s OF must
disable interrupts from the using virtual IOA upon deregistering the
IOA&#8217;s CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-23.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must present (as
appropriate per RTAS control of the interrupt source number) the
partition owning a CRQ the appearance of an interrupt, from the interrupt
source number associated, through the OF device tree node, with the
virtual device, when a new entry is enqueued to the virtual
device&#8217;s CRQ and when the last interrupt mode set was
&#8220;Enabled&#8221;, unless a previous interrupt from the interrupt
source number is still outstanding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_69369"
xrefstyle="select: labelnumber nopage"/>-24.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the CRQ facility:</emphasis> The platform must not present
the partition owning a CRQ the appearance of an interrupt, from the
interrupt source number associated, through the OF device tree node, with
the virtual device, if the last interrupt mode set was
&#8220;Disabled&#8221;, unless a previous interrupt from the interrupt
source number is still outstanding.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569348_25634">
<title>Redirected RDMA (Using H_PUT_RTCE, and
H_PUT_RTCE_INDIRECT)</title>
<para>A server partition uses the hypervisor function, H_PUT_RTCE, which
takes as a parameter the opaque handle (LIOBN) of the partner
partition&#8217;s RTCE table (second window pane of
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>), an offset in the
RTCE table, the handle for one of the server partition's I/O adapter TCE
tables plus an offset within the I/O adapter's TCE table. H_PUT_RTCE then
copies the appropriate contents of the partner partition's RTCE table
into the server partition's I/O adapter TCE table. In effect, this
hcall() allows the server partition's I/O adapter to have access to a
specific section of the partner partition's memory as if it were the
server partition's memory. However, the partner partition, through the
hypervisor, maintains control over exactly which areas of the partner
partition's memory are made available to the server partition without the
overhead of the hypervisor having to directly handle each byte of the
shared data.</para>
<para>The H_PUT_RTCE_INDIRECT, if implemented, takes as an input
parameter a pointer to a list of offsets into the RTCE table, and builds
the TCEs similar to the H_PUT_RTCE, described above.</para>
<para>A server partition uses the hypervisor function, H_REMOVE_RTCE, to
back-out TCEs generated by the H_PUT_RTCE and H_PUT_RTCE_INDIRECT
hcall()s.</para>
<para>The following rules guide the definition of the RTCE table entries
and implementation of the H_PUT_RTCE, H_PUT_RTCE_INDIRECT, H_REMOVE_RTCE,
H_MASS_MAP_TCE, H_PUT_TCE, H_PUT_TCE_INDIRECT, and H_STUFF_TCE hcall()s.
Other implementations that provide the same external appearance as these
rules are acceptable. The architectural intent is to provide RDMA
performance essentially equivalent to direct TCE operations.</para>
<orderedlist>
<listitem>
<para>The partner partition's RTCE table is itself never directly
accessed by an I/O Adapter (IOA), it is only accessed by the hypervisor,
and therefore it can be a bigger structure than the regular TCE table as
accessed by hardware (more fields).</para>
</listitem>
<listitem>
<para>When a server partition asks (via an H_PUT_RTCE or
H_PUT_RTCE_INDIRECT hcall()) to have an RTCE table TCE copied to one of
the server partition's physical IOA's TCEs, or asks (via an
H_REMOVE_RTCE) to have an RTCE table entry removed from one of the server
partition&#8217;s physical IOA&#8217;s TCEs, the hypervisor atomically,
with respect to all RTCE table readers, sets (H_PUT_RTCE or
H_PUT_RTCE_INDIRECT) or removes (H_REMOVE_RTCE) a field in the copied
RTCE table entry<footnote xml:id="pgfId-997540">
<para>This is an example of where the earlier statement &#8220;Other
implementations that provide the same external appearance as these
rules are acceptable&#8221; comes into affect. For example, for an RTCE
table that is mapped with H_MASS_MAP_TCE, the pointer may not be in a
field of the actual TCE in the RTCE table, but could, for example, be
in a linked list, or other such structure, due to the fact that there
is not a one-to-one correspondence from the RTCE to the physical IOA
TCE in that case (H_MASS_MAP_TCE can map up to an LMB into one TCE, and
physical IOA TCEs only map 4 KB).</para>
</footnote>. This field is a pointer to the copy of the RTCE table TCE in
the server partition&#8217;s IOA&#8217;s TCE table. (A per RTCE table TCE
lock is one method for the atomic setting of the copied RTCE table TCE
link pointer.)</para>
</listitem>
<listitem>
<para>A server partition is guaranteed that it can create one redirected
mapping per RTCE table entry. By default if the
server partition tries to create another copy of the same RTCE table TCE
it gets an error return. Platforms that support
the H_VIOCTL hcall() might support multiple redirected
RTCE table mappings provided that they do not duplicate
existing mappings (the mappings are for different I/O operations);
if they do, the total number of such
multiple mappings per LIOBN and per RTCE page is communicated by the
“GET_MAX_REDIRECTED_MAPPINGS” sub-function of the H_VIOCTL hcall(). If the
“GET_MAX_REDIRECTED_MAPPINGS” sub-function of the
H_VIOCTL hcall() is not implemented then only
the default single copy is supported.</para>
<note><para>Multiple mappings
of the same physical page are always allowed, as
long as they originate from different RTCE table TCEs
just like with physical IOA TCEs.</para></note>
</listitem>
<listitem>
<para>When the partner partition issues an H_PUT_TCE,
H_PUT_TCE_INDIRECT, H_STUFF_TCE, or H_MASS_MAP hcall() to change his RTCE
table, the hypervisor finds the TCE tables in one of several states. A
number of these states represent unusual conditions, that can arise from
timing windows or error conditions. The hypervisor rules for handling
these cases are chosen to minimize its overhead while preventing one
partition&#8217;s errors from corrupting another partition&#8217;s
state.</para>
<orderedlist>
<listitem>
<para>The RTCE table TCE is not currently in use: Clear/invalidate the
TCE copy pointer and enter the RTCE table TCE mapping per the input
parameters to the hcall().</para>
</listitem>
<listitem>
<para>The RTCE table TCE contains a valid mapping and the TCE copy
pointer is invalid (NULL or other implementation dependent value) (The
previous mapping was never used for Redirected RDMA): Enter the RTCE
table TCE mapping per the input parameters to the hcall().</para>
</listitem>
<listitem>
<para>The RTCE table TCE contains a valid mapping and the TCE copy
pointers reference TCEs that do not contain a valid copy of the
previous mapping in the RTCE table TCE. (The previous mapping was used
for Redirected RDMA, however, the server partition has moved on and is no
longer targeting the page represented by the old RTCE table TCE mapping):
Clear/invalidate the TCE copy pointers and enter the RTCE table TCE
mapping per the input parameters to the hcall().</para>
</listitem>
<listitem>
<para>The RTCE table TCE contains a valid mapping and the TCE copy
pointers reference TCEs that do contain a valid copy of the previous
mapping in the RTCE table TCE (the previous mapping is still potentially
in use for Redirected RDMA, however, the partner partition has moved on
and is no longer interested in the previous I/O operation). The server
partition&#8217;s IOA may still target a DMA operation against the TCE
containing the copy of the RTCE table TCE mapping. The assumption is that
any such targeting is the result of a timing window in the recovery of
resources in the face of errors. Therefore, the server partition&#8217;s
TCE is considered invalid, but the server partition may or may not be
able to immediately invalidate the TCEs. For more information on
invalidation of TCEs, see
<xref linkend="dbdoclet.50569348_69987" />. The H_Resource return from an
H_PUT_TCE, H_PUT_TCE_INDIRECT, and H_STUFF_TCE may be used to hold off
invalidation in this case.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>If a server partition terminates, the partner partition&#8217;s
device drivers time out the operations and resource recovery code
recovers the RTCE table TCEs. If the partner partition terminates, the
hypervisor scans the RTCE table and eventually invalidates all active
copies of RTCE table TCEs. For more information on invalidation of TCEs,
see <xref linkend="dbdoclet.50569348_69987" />.</para>
</listitem>
<listitem>
<para>The server partition may use any of the supported hcall()s (see
<xref linkend="dbdoclet.50569348_40629" />) to manage the TCE tables used
by its IOAs. No extra restrictions are made to changes of the server
partition's TCE table beside those stated in 2 above. The server
partition can only target its own memory or the explicitly granted
partner partition&#8217;s memory.</para>
</listitem>
<listitem>
<para>The H_MIGRATE_DMA hcall() made by a partner partition migrates
the page referenced by the RTCE table TCE but follows the RTCE table TCE
copy pointer, if valid, to the server partition&#8217;s IOA&#8217;s TCE
table to determine which IOA&#8217;s DMA to disable, thus allowing
migration of partner partition pages underneath server partition DMA
activity. In this case, however, the H_MIGRATE_DMA algorithm is modified
such that server partition&#8217;s IOA&#8217;s TCE table is atomically
updated, after the page migration but prior to enabling the IOA&#8217;s
DMA, only when its contents still are a valid copy of the partner
partition&#8217;s RTCE table TCE contents. The H_MIGRATE_DMA hcall() also
serializes with H_PUT_RTCE so that new copies of the RTCE table TCE are
not made during the migration of the underlying page.</para>
</listitem>
<listitem>
<para>The server partition should never call H_MIGRATE_DMA for any
Redirected RDMA mapped pages, however, to check, the H_MIGRATE_DMA
hcall() is enhanced to check the Logical Memory Block (LMB) owner in the
TCE and reject the call if the LMB did not belong to the
requester.</para>
</listitem>
</orderedlist>
<section xml:id="dbdoclet.50569348_96734">
<title>H_PUT_RTCE</title>
<para>This hcall() maps &#8220;count&#8221; number of contiguous TCEs in
an RTCE to the same number of contiguous IOA TCEs. The H_REMOVE_RTCE
hcall() is used to back-out TCEs built with H_PUT_RTCE hcall().
<xref linkend="dbdoclet.50569348_87976" /> for that hcall().</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid -- */
/* no mappings changed */
/* H_RESCINDED: A specified parameter refers to a rescinded */
/* shared logical resource. (no mappings changed) */
/* H_R_Parm: One or more r-ioba mappings are invalid -- */
/* mappings may have changed */
/* H_Resource: An attempt was made to make more */
/* redirected mappings of an RTCE table entry than the */
/* platform supports -- some mappings may have changed. */
/* H_IN_USE: An attempt was made to duplicate a redirected */
/* mapping */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */
uint64 r-liobn, /* handle of RDMA RTCE table */
uint64 r-ioba, /* IO address per RDMA RTCE table */
uint64 liobn, /* Logical I/O Bus Number of server TCE table */
uint64 ioba, /* I/O address as seen by server IOA */
uint64 count /* Number of consecutive 4 KB pages to map */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>r-liobn: Handle of RDMA RTCE table</para>
</listitem>
<listitem>
<para>r-ioba: IO address per RDMA RTCE table</para>
</listitem>
<listitem>
<para>liobn: Logical I/O Bus Number of server TCE table</para>
</listitem>
<listitem>
<para>ioba: I/O address as seen by server IOA</para>
</listitem>
<listitem>
<para>count: Number of consecutive 4 KB pages to map</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validates r-liobn is from the second triple (second window pane)
of the server partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validates r-ioba plus (count * 4 KB) is within range of RTCE
table as specified by the window pane as specified by the r-liobn, else
return H_Parameter.</para>
</listitem>
<listitem>
<para>Validates that the TCE table associated with liobn is owned by
calling partition, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the
LIOBN, represents a logical resource that has been rescinded by the
owner, return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Validates that ioba plus (count * 4 KB) is within the range of
TCE table specified by liobn, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the IOBA
represents a logical resource that has been rescinded by the owner,
return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For count entries</para>
<itemizedlist>
<listitem>
<para>The following is done in a critical section with respect to
updates to the r-ioba entry of the RTCE table TCE</para>
<itemizedlist>
<listitem>
<para>Check that the r-ioba entry of the RTCE table contains a valid
mapping (this requires having a completed partner connection), else
return H_R_Parm with the value of the loop count in R4.</para>
</listitem>
<listitem>
<para>Prevent more redirected mappings of the same r-ioba than
the platform supports and/or duplicates: If the r-ioba
entry of the RTCE table TCE contains a valid pointer, and
if that pointer references a TCE that is a clone of the
r-ioba entry of the RTCE table TCE, then an additional
redirected mapping, if supported, is used else return
H_Resource with the value of the loop count in R4.</para>
<itemizedlist>
<listitem>
<para>Validate the liobn and ioba are not already mapped for
this entry else return H_IN_USE with the value of the
loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the number of redirected mappings for the
r-ioba does not exceed the
<emphasis role="bold"><literal>&#8220;ibm,max-rtce-mappings&#8221;</literal></emphasis>
value for any of the adapters mapped by the RTCE else
return H_Resource with the value of the loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the number of redirected mappings for the r-ioba
does not exceed the per client IOBA value returned
from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function
else return H_Resource with the value of the loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the new entry will not cause the number of
additional redirected mappings that have already been
made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL
GET_MAX_REDIRECTED_MAPPINGS sub-function else return
H_Resource with the value of the loop count in R4.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Copy the DMA address mapping from the r-ioba entry of the r-liobn
RTCE table to the ioba entry of the liobn TCE table and save a pointer to
the ioba entry of the liobn TCE table in the r-ioba entry of the r-liobn
RTCE table, or in a separate structure associated with the r-liobn RTCE
table.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>End Loop (The critical section lasts for one iteration of the
loop)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> The PA requires the OS to issue a sync
instruction to proceed the signalling of an IOA to start an IO operation
involving DMA to guarantee the global visibility of both DMA and TCE
data. This hcall() does not include a sync instruction to guarantee
global visibility of TCE data and in no way diminishes the requirement
for the OS to issue it.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> The execution time for this hcall() is
expected to be a linear function of the count parameter. Excessive size
of the count parameter may cause an extended delay.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_99406">
<title>H_PUT_RTCE_INDIRECT</title>
<para>This hcall() maps &#8220;count&#8221; number of potentially
non-contiguous TCEs in an RTCE to the same number of contiguous IOA TCEs.
The H_REMOVE_RTCE hcall() is used to back-out TCEs built with the
H_PUT_RTCE_INDIRECT hcall().
<xref linkend="dbdoclet.50569348_87976" /> for that hcall().</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid -- */
/* no mappings changed. */
/* H_RESCINDED: A specified parameter refers to a rescinded */
/* shared logical resource (No mappings changed)
/* H_R_Parm: One or more r-ioba mappings are invalid -- */
/* mappings may have changed */
/* H_Resource: An attempt was made to make more */
/* redirected mappings of an RTCE table entry than the */
/* platform supports -- some mappings may have changed. */
/* H_IN_USE: An attempt was made to duplicate a redirected */
/* mapping */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */
uint64 buff-addr, /* The Logical Address of a page (4 KB, 4 KB boundary) */
/* containing a list of r-ioba to be mapped using the */
/* r-liobn RTCE table */
uint64 r-liobn, /* handle of RTCE table to be used with r-ioba entries in */
/* indirect buffer (second window pane from server */
/* “ibm,my-dma-window”) */
uint64 liobn, /* Logical I/O Bus Number of server TCE table */
uint64 ioba, /* I/O address as seen by server IOA */
uint64 count /* Number of consecutive IOA bus 4 KB pages to map (number */
/* of entries in bufr) */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>buff-addr: The Logical Address of a page (4 KB, 4 KB boundary)
containing a list of r-ioba to be mapped via using the r-liobn RTCE
table</para>
</listitem>
<listitem>
<para>r-liobn: Handle of RTCE table to be used with r-ioba entries in
indirect buffer (second window pane from server
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis></para>
</listitem>
<listitem>
<para>liobn: Logical I/O Bus Number of server TCE table</para>
</listitem>
<listitem>
<para>ioba: I/O address as seen by server IOA</para>
</listitem>
<listitem>
<para>count: Number of consecutive IOA bus 4 KB pages to map (number of
entries in buffer)</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validates r-liobn is from the second triple (second window pane)
of the server partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validates buff-addr points to the beginning of a 4 KB page owned
by the calling partition, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the
logical address&#8217;s page number represents a page that has been
rescinded by the owner, return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Validates that the TCE table associated with liobn is owned by
calling partition, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the
LIOBN represents a logical resource that has been rescinded by the owner,
return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Validates that ioba plus (count * 4 KB) is within the range of
TCE table specified by liobn, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the IOBA
represents a logical resource that has been rescinded by the owner,
return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the count field is greater than 512 return H_Parameter.</para>
</listitem>
<listitem>
<para>Copy (count * 8) bytes from the page specified by buff-addr to a
temporary hypervisor page for contents verification and processing (this
avoids the problem of the caller changing call by reference values after
they are checked).</para>
</listitem>
<listitem>
<para>For count entries:</para>
<itemizedlist>
<listitem>
<para>Validate the r-ioba entry in the temporary page is within range
of RTCE table as specified by r-liobn, else place the count number in R4
and return H_R_Parm.</para>
</listitem>
<listitem>
<para>End loop</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For count validated entries in the hypervisor's temporary
page:</para>
<itemizedlist>
<listitem>
<para>The following is done in a critical section with respect to
updates to the r-ioba entry of the RTCE</para>
<itemizedlist>
<listitem>
<para>Check that the r-ioba entry of the r-liobn RTCE table contains a
valid mapping (this requires having a completed partner connection), else
return H_R_Parm with the count number in R4.</para>
</listitem>
<listitem>
<para>Prevent more redirected mappings of the same r-ioba than
the platform supports and/or duplicates: If the r-ioba
entry of the RTCE table TCE contains a valid pointer, and
if that pointer references a TCE that is a clone of the
r-ioba entry of the RTCE table TCE, then an additional
redirected mapping, if supported, is used else return
H_Resource with the value of the loop count in R4.</para>
<itemizedlist>
<listitem>
<para>Validate the liobn and ioba are not already mapped for
this entry else return H_IN_USE with the value of the
loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the number of redirected mappings for the
r-ioba does not exceed the
<emphasis role="bold"><literal>&#8220;ibm,max-rtce-mappings&#8221;</literal></emphasis>
value for any of the adapters mapped by the RTCE else
return H_Resource with the value of the loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the number of redirected mappings for the r-ioba
does not exceed the per client IOBA value returned
from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function
else return H_Resource with the value of the loop count in R4.</para>
</listitem>
<listitem>
<para>Validate the new entry will not cause the number of
additional redirected mappings that have already been
made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL
GET_MAX_REDIRECTED_MAPPINGS sub-function else return
H_Resource with the value of the loop count in R4.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Copy the DMA address mapping from the r-ioba entry of the r-liobn
RTCE table to the ioba entry of the liobn TCE table and save a pointer to
the ioba entry of the liobn TCE table in the r-ioba entry of the r-liobn
RTCE table, or into a separate structure associated with the r-liobn RTCE
table.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>End Loop (The critical section lasts for one iteration of the
loop)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> The PA requires the OS to issue
a sync instruction to proceed the signalling of an IOA to start an IO
operation involving DMA to guarantee the global visibility of both DMA
and TCE data. This hcall() does not include a sync instruction to
guarantee global visibility of TCE data and in no way diminishes the
requirement for the OS to issue it.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> The execution time for this
hcall is expected to be a linear function of the count parameter.
Excessive size of the count parameter may cause an extended delay.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_87976">
<title>H_REMOVE_RTCE</title>
<para>The H_REMOVE_RTCE hcall() is used to back-out TCEs built with
H_PUT_RTCE and H_PUT_RTCE_INDIRECT hcall()s. That is, to remove the TCEs
from the IOA TCE table and links put into the RTCE table as a result of
the H_PUT_RTCE or H_PUT_RTCE_INDIRECT hcall()s.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid -- */
/* no mappings changed */
/* H_RESCINDED: A specified parameter refers to a rescinded */
/* shared logical resource. (no mappings changed) */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */
uint64 r-liobn, /* handle of RDMA RTCE table */
uint64 r-ioba, /* IO address per RDMA RTCE table */
uint64 liobn, /* Logical I/O Bus Number of server TCE table */
uint64 ioba, /* I/O address as seen by server IOA */
uint64 count /* Number of consecutive 4 KB pages to map */
uint64 tce-value /* TCE value to be put into the IOA TCE (Page Mapping and */
/* Control bits will be set to “Page fault (no access) by */
/* the hcall before replacing the IOA TCE) */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>r-liobn: Handle of RDMA RTCE table</para>
</listitem>
<listitem>
<para>r-ioba: IO address per RDMA RTCE table</para>
</listitem>
<listitem>
<para>liobn: Logical I/O Bus Number of server TCE table</para>
</listitem>
<listitem>
<para>ioba: I/O address as seen by server IOA</para>
</listitem>
<listitem>
<para>count: Number of consecutive 4 KB pages to unmap</para>
</listitem>
<listitem>
<para>tce-value: TCE value to be put into the IOA TCE(s) after setting
the &#8220;Page Mapping and Control&#8221; bits to &#8220;Page fault (no
access)&#8221;.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validates r-liobn is from the second triple (second window pane)
of the server partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validates r-ioba plus (count * 4 KB) is within range of RTCE
table as specified by the window pane as specified by the r-liobn, else
return H_Parameter.</para>
</listitem>
<listitem>
<para>Validates that the TCE table associated with liobn is owned by
calling partition, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the
LIOBN, represents a logical resource that has been rescinded by the
owner, return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Validates that ioba plus (count * 4 KB) is within the range of
TCE table specified by liobn, else return H_Parameter.</para>
<itemizedlist>
<listitem>
<para>If the Shared Logical Resource option is implemented and the IOBA
represents a logical resource that has been rescinded by the owner,
return H_RESCINDED.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For count entries</para>
<itemizedlist>
<listitem>
<para>The following is done in a critical section with respect to
updates the r-ioba entry of the RTCE table TCE</para>
<itemizedlist>
<listitem>
<para>If it exists, invalidate the pointer in the r-ioba entry of the
r-liobn RTCE table (or in a separate structure associated with the
r-liobn RTCE table).</para>
</listitem>
<listitem>
<para>Replace the ioba entry of the liobn TCE table with tce-value
after setting the &#8220;Page Mapping and Control&#8221; bits to
&#8220;Page fault (no access)&#8221;.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>End Loop (The critical section lasts for one iteration of the
loop)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Return H_Success</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> The execution time for this hcall() is
expected to be a linear function of the count parameter. Excessive size
of the count parameter may cause an extended delay.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_69987">
<title>Redirected RDMA TCE Recovery and In-Flight DMA</title>
<para>There are certain error or error recovery scenarios that may
attempt to unmap a TCE in an IOA&#8217;s TCE table prior to the
completion of the operation which setup the TCE. For example:</para>
<itemizedlist>
<listitem>
<para>A client attempts to H_PUT_TCE to its DMA window pane, which is
mapped to the second window pane of the server&#8217;s DMA window, and
the TCE in the RTCE table which is the target of the H_PUT_TCE already
points to a valid TCE in an IOA&#8217;s TCE table.</para>
</listitem>
<listitem>
<para>A client attempts to H_FREE_CRQ and the server&#8217;s second
window pane for that virtual IOA contains a TCE which points to a valid
TCE in an IOA&#8217;s TCE table.</para>
</listitem>
<listitem>
<para>A client partition attempts to reboot (which essentially is an
H_FREE_CRQ).</para>
</listitem>
<listitem>
<para>A server attempts to H_FREE_CRQ and the server&#8217;s second
window pane for that virtual IOA contains a TCE which points to a valid
TCE in an IOA&#8217;s TCE table.</para>
</listitem>
</itemizedlist>
<para>In such error and error recovery situations, the hypervisor
attempts to prevent the changing of an IOAs TCE to a value that would
cause a non-recoverable IOA error. One method that the hypervisor may use
to accomplish this is that on a TCE invalidation operation, set the value
of the read and write enable bits in the TCE to allow DMA writes but not
reads, and to change the real page number in the TCE to target a dummy
page. In this case the IOA receives an error (Target Abort) on attempts
to read, while DMA writes (which were for a defunct operation) are
silently dropped. This works well when all the following are true:</para>
<itemizedlist>
<listitem>
<para>The platform supports separate TCE read and write enable bits in
the TCE</para>
</listitem>
<listitem>
<para>EEH is enabled and the DD can recover from the MMIO Stopped and
DMA Stopped states</para>
</listitem>
<listitem>
<para>The IOA and the IOA&#8217;s DD can recover gracefully from Target
Aborts (which are received on a read to a page where the read enable bit
is off)</para>
</listitem>
</itemizedlist>
<para>If these conditions are not true then the hypervisor will need to
try to prevent or delay invalidation of the TCEs. The H_Resource return
from the H_FREE_CRQ, H_PUT_TCE, H_PUT_TCE_INDIRECT, and H_STUFF_TCE can
be used to hold-off the invalidation until which time the IOA can
complete the operation and the server can invalidate the IOA&#8217;s TCE.
In addition, the Bit Bucket Allowed LIOBN attribute and the
H_LIOBN_ATTRIBUTES hcall can be used to help enhance the recoverability
in these error scenarios (see
<xref linkend="dbdoclet.50569348_55353" /> and
<xref linkend="dbdoclet.50569348_67792" /> for more information).</para>
</section>
<section xml:id="dbdoclet.50569348_55353">
<title>LIOBN Attributes</title>
<para>There are certain LIOBN attributes that are made visible to and can
be manipulated by partition software. The H_LIOBN_ATTRIBUTES hcall is
used to read and modify the attributes (see
<xref linkend="dbdoclet.50569348_67792" />).
<xref linkend="dbdoclet.50569348_11661" /> defines the attributes that are
visible and manipulatable.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_11661">
<title>LIOBN Attributes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Bit(s)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0-62</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>63</para>
</entry>
<entry>
<para>Bit Bucket Allowed</para>
</entry>
<entry>
<para>1: For an indirect IOA TCE invalidation operation (that
is, via an operation other than an H_PUT_TCE directly to the
TCE by the partition owning the IOA), the platform may set the
value of the read and write enable bits in the TCE to allow DMA
writes but not reads and change the real page number in the TCE
to target a dummy page (the IOA receives an error (Target
Abort) on attempts to read, while DMA writes (which were for a
defunct operation) are silently dropped).</para>
<para>0: The platform must reasonably attempt to prevent an
indirect (that is, via an operation other than an H_PUT_TCE
directly to the TCE by the partition owning the IOA)
modification an IOA&#8217;s valid TCE so that a possible
in-flight DMA does not cause a non-recoverable error.</para>
<para><emphasis role="bold">Software Implementation Notes:</emphasis>
<orderedlist>
<listitem>
<para>The results of changing this field when there are
valid TCEs for the LIOBN may produce unexpected results. The
hypervisor is not required to prevent such an operation.
Therefore, the H_LIOBN_ATTRIBUTES call to change the value of
this field should be made when there are no valid TCEs in the
table for the IOA.</para>
</listitem>
<listitem>
<para>This field may be implemented but not changeable (the
actual value will be returned in R4 as a result of the
H_LIOBN_ATTRIBUTES hcall() regardless, with a status of
H_Constrained if not changeable).</para>
</listitem>
</orderedlist>
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="dbdoclet.50569348_67792">
<title>H_LIOBN_ATTRIBUTES</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_67792"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>If the H_LIOBN_ATTRIBUTES hcall is
implemented, then it must implement the attributes as they are defined in
<xref linkend="dbdoclet.50569348_11661" /> and the syntax and semantics as
defined in
<xref linkend="dbdoclet.50569348_67792" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_67792"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The H_LIOBN_ATTRIBUTES hcall must
ignore bits in the set-mask and reset-mask which are not implemented and
must process as an exception those which cannot be changed (H_Constrained
returned), and must return the following for the LIOBN Attributes in
R4:</para>
</listitem>
</varlistentry>
</variablelist>
<orderedlist numeration="loweralpha">
<listitem>
<para>A value of 0 for unimplemented bit positions.</para>
</listitem>
<listitem>
<para>The resultant field values for implemented fields.</para>
</listitem>
</orderedlist>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more parameters were in error */
/* H_Constrained: One or more parameters were not changeable */
/* to the value requested. The result was constrained to a */
/* legitimate value for the implementation */
/* H_Hardware: Operation failed because of hardware error */
hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */
/* Attributes */
uint64 liobn, /* The LIOBN on which to perform this operation*/
uint64 reset-mask, /* Mask of Attribute bits to be reset*/
uint64 set-mask /* Mask of Attribute bits to be set*/
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>liobn: The LIOBN on which this Attribute modification is to be
performed.</para>
<para>reset-mask: The bit-significant mask of bits to be reset in the
LIOBN&#8217;s Attributes (the reset-mask bit definition aligns with the
bit definition of the LIOBN&#8217;s Attributes, as defined in
<xref linkend="dbdoclet.50569348_11661" />). The complement of the
reset-mask is ANDed with the LIOBN&#8217;s Attributes, prior to applying
the set-mask. See semantics for more details on any field-specific
actions needed during the reset operations. If a particular field
position in the LIOBN Attributes is not implemented, then the
corresponding bit(s) in the reset-mask are ignored.</para>
<para>set-mask: The bit-significant mask of bits to be set in the
LIOBN&#8217;s Attributes (the set-mask bit definition aligns with the bit
definition of the LIOBN&#8217;s Attributes, as defined in
<xref linkend="dbdoclet.50569348_11661" />). The set-mask is ORed with
the LIOBN&#8217;s Attributes, after to applying the reset-mask. See
semantics for more details on any field-specific actions needed during
the set operations. If a particular field position in the LIOBN
Attributes is not implemented, then the corresponding bit(s) in the
set-mask are ignored.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that liobn belongs to the partition, else
H_Parameter.</para>
</listitem>
<listitem>
<para>If the Bit Bucket Allowed field of the specified LIOBN&#8217;s
Attributes is implemented and changeable, then set it to the result
of:</para>
<para>Bit Bucket Allowed field contents ANDed with the complement of the
corresponding bits of the reset-mask and then ORed with the corresponding
bits of the set-mask.</para>
</listitem>
<listitem>
<para>Load R4 with the value of the LIOBN&#8217;s Attributes, with any
unimplemented bits set to 0, and if all requested changes were made, then
return H_Success, otherwise return H_Constrained.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section>
<title>Extensions to Other hcall()s for Redirected
RDMA</title>
<para />
<section xml:id="dbdoclet.50569348_15493">
<title>H_PUT_TCE, H_PUT_TCE_INDIRECT, and
H_STUFF_TCE</title>
<para>These hcall()s are only valid for the first window pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. See
<xref linkend="dbdoclet.50569348_40629" /> for information about window
pane types.</para>
<para>The following are extensions that apply to the H_PUT_TCE,
H_PUT_TCE_INDIRECT, and H_STUFF_TCE hcall()s in their use against an RTCE
table.</para>
<para>Recognize the validated (owned by the calling partition, else
H-Parameter) LIOBN as referring to a RTCE table (first window pane) and
access accordingly:</para>
<itemizedlist>
<listitem>
<para>If the TCE is not from the first triple (first window pane) of
the calling partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, return
H_Parameter.</para>
</listitem>
<listitem>
<para>If the TCE is not currently in use: Clear/invalidate the TCE copy
pointer and enter the TCE mapping per the input parameters to the
hcall().</para>
</listitem>
<listitem>
<para>If the TCE contains a valid mapping and the TCE copy pointer is
invalid: Enter the TCE mapping per the input parameters to the
hcall().</para>
</listitem>
<listitem>
<para>If the TCE contains a valid mapping and the TCE copy pointer
references a TCE that does not contain a valid copy of the previous
mapping in the TCE: Clear/invalidate the TCE copy pointer and enter the
TCE mapping per the input parameters to the hcall().</para>
</listitem>
<listitem>
<para>If the TCE contains a valid mapping and the TCE copy pointer
references a TCE that does contain a valid copy of the previous mapping
in the TCE, then:</para>
<itemizedlist>
<listitem>
<para>If the Bit Bucket Allowed Attribute of the LIOBN containing the
TCE is a 1, invalidate the copied TCE and enter the TCE mapping per the
input parameters to the hcall().</para>
</listitem>
<listitem>
<para>If the Bit Bucket Allowed Attribute of the LIOBN containing the
TCE is a 0, then return H_Resource or perform some other
platform-specific error recovery.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569348_15120">
<title>H_MIGRATE_DMA</title>
<para>Check that the pages referenced by the TCEs specified in the
mappings to be migrated belong to the calling partition, else
H_Parameter.</para>
<para>If the mapping being migrated is via an RTCE table (that is, LIOBN
points to an RTCE table), then follow the valid redirected TCE pointer
and migrate the redirected page (if the redirected TCE mapping is still a
clone of the original RTCE table entry).</para>
<para>If the mapping being migrated is via an RTCE table and if the RTCE
table TCEs were built with the H_MASS_MAP_TCE hcall(), then expand each
mass mapped area into smaller 4 KB granularities, as necessary to avoid
performance and locking issues, during the migration process.</para>
<para>Insert checking, and potentially delays, to allow IOAs to make
forward progress between successive DMA disables caused by multiple
partner partitions making simultaneous uncoordinated calls to
H_MIGRATE_DMA targeting the same IOA.</para>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569348_92689">
<title>Subordinate Command/Response Queue (Sub-CRQ)</title>
<para>The Sub-CRQ facility is used in conjunction with the CRQ facility,
for some virtual IOA types, when more than one queue is needed for the
virtual IOA. For information on the CRQ facility, see
<xref linkend="dbdoclet.50569348_98947" />. For information on which
virtual IOAs may use the Sub-CRQ facilities, see the applicable sections
for the virtual IOAs. See
<xref linkend="dbdoclet.50569348_26160" /> for a comparison of the
differences in the queue structures between CRQs and Sub-CRQs. In
addition to the hcall()s specified in
<xref linkend="dbdoclet.50569348_26160" />, all of the following hcall()s
and RTAS calls are applicable to both CRQs and Sub-CRQs:</para>
<itemizedlist>
<listitem>
<para>H_XIRR</para>
</listitem>
<listitem>
<para>H_EOI</para>
</listitem>
<listitem>
<para>ibm,int-on</para>
</listitem>
<listitem>
<para>ibm,int-off</para>
</listitem>
<listitem>
<para>ibm,set-xive</para>
</listitem>
<listitem>
<para>ibm,get-xive</para>
</listitem>
</itemizedlist>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_26160">
<title>CRQ and Sub-CRQ Comparison</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Characteristic</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">CRQ</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Sub-CRQ</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Queue entry size</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>32</para>
</entry>
</row>
<row>
<entry>
<para>Transport and initialization events</para>
</entry>
<entry>
<para>Applicable</para>
</entry>
<entry>
<para>Not applicable (coordinated through the CRQ that is
associated with the Sub-CRQ)</para>
</entry>
</row>
<row>
<entry>
<para>Registration</para>
</entry>
<entry>
<para>H_REG_CRQ</para>
</entry>
<entry>
<para>H_REG_SUB_CRQ</para>
</entry>
</row>
<row>
<entry>
<para>Deregistration</para>
</entry>
<entry>
<para>H_FREE_CRQ</para>
</entry>
<entry>
<para>H_FREE_SUB_CRQ</para>
<para><emphasis role="bold">Note:</emphasis> H_FREE_CRQ for the associated CRQ implicitly
deregisters the associated Sub-CRQs</para>
</entry>
</row>
<row>
<entry>
<para>Enable</para>
</entry>
<entry>
<para>H_ENABLE_CRQ</para>
</entry>
<entry>
<para>Not applicable</para>
</entry>
</row>
<row>
<entry>
<para>Interrupt number</para>
</entry>
<entry>
<para>Obtained from
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property</para>
</entry>
<entry>
<para>Obtained from H_REG_SUB_CRQ</para>
</entry>
</row>
<row>
<entry>
<para>Interrupt enable/disable</para>
</entry>
<entry>
<para>H_VIO_SIGNAL</para>
</entry>
<entry>
<para>H_VIOCTL subfunction<footnote xml:id="pgfId-1200839">
<para>For virtual IOAs that define the use of Sub-CRQs, the
interrupt associated with the CRQ, as defined by the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property in the
OF device tree, may be enabled or disabled with either the
H_VIOCTL or the H_VIO_SIGNAL hcall(). The CRQ interrupt
associated with a CRQ of a virtual IOA that does not define
the use of Sub-CRQs should be enabled and disabled by use of
the H_VIO_SIGNAL hcall().</para>
</footnote></para>
</entry>
</row>
<row>
<entry>
<para>hcall() used to place entry on queue</para>
</entry>
<entry>
<para>H_SEND_CRQ</para>
</entry>
<entry>
<para>H_SEND_SUB_CRQ</para>
<para>H_SEND_SUB_CRQ_INDIRECT</para>
</entry>
</row>
<row>
<entry>
<para>Number of queues per virtual IOA</para>
</entry>
<entry>
<para>One</para>
</entry>
<entry>
<para>Zero or more, depending on virtual IOA architecture,
implementation, and client/server negotiation</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<section>
<title>Sub-CRQ Format and Registration</title>
<para>Each Sub-CRQ is built of one or more 4 KB pages aligned on a 4 KB
boundary within partition memory, and is organized as a circular buffer
of 32 byte long elements. Each queue is mapped into contiguous I/O
addresses via the TCE mechanism and RTCE table (first window pane). The
I/O address and length of each queue is registered by the process defined
in
<xref linkend="dbdoclet.50569348_10878" />. This registration process
tells the hypervisor where to find the virtual IOA&#8217;s
Sub-CRQ(s).</para>
</section>
<section xml:id="dbdoclet.50569348_78758">
<title>Sub-CRQ Entry Format</title>
<para>Each Sub-CRQ entry consists of a 32 byte element. The first byte of
a Sub-CRQ entry is the Header byte and is defined in
<xref linkend="dbdoclet.50569348_26980" />.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569348_26980">
<title>Sub-CRQ Entry Header Byte Values</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Header Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Element is unused -- all other bytes in the element are
undefined.</para>
</entry>
</row>
<row>
<entry>
<para>0x01 - 0x7F</para>
</entry>
<entry>
<para>Reserved.</para>
</entry>
</row>
<row>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Command/Response entry.</para>
</entry>
</row>
<row>
<entry>
<para>0x81 - 0xFF</para>
</entry>
<entry>
<para>Reserved.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The platform (transport mechanism) ignores the contents of all
non-header bytes in all Sub-CRQ entries.</para>
<para>The operational state of any Sub-CRQs follows the operational state
of the CRQ to which the Sub-CRQ is associated. That is, the CRQ transport
is required to be operational in order for any associated Sub-CRQs to be
operational (for example, if an H_SEND_CRQ hcall() would not succeed due
to any reason other than lack of space is available in the CRQ, then an
H_SEND_SUB_CRQ or H_SEND_SUB_CRQ_INDIRECT hcall() to the associated
Sub-CRQ would also fail). Hence, the Sub-CRQ transport does not implement
the transport and initialization events that are implemented by the CRQ
facility.</para>
</section>
<section>
<title>Sub-CRQ Entry Processing</title>
<para>During the Sub-CRQ registration (H_REG_SUB_CRQ), the platform
firmware sets all the header bytes of the Sub-CRQ being registered to
zero (entry invalid). After registration, the first valid entry is placed
in the first element and the process proceeds to the end of the queue and
then wraps around to the first entry again (given that the entry has been
subsequently marked as invalid). This allows both the partition software
and transport firmware to maintain independent pointers to the next
element they will be respectively using.</para>
<para>A sender uses an H_SEND_SUB_CRQ hcall() to enter one 32 byte
message on its partner&#8217;s Sub-CRQ. Prior to enqueueing an entry on
the Sub-CRQ, the platform first checks if the session to the
partner&#8217;s associate CRQ is open, and there is a enough free space
on the Sub-CRQ, if not, it returns an error. If the checks succeed, the
contents of the message is copied into the next free queue element,
potentially notifying the receiver, and returns a successful status to
the caller. The caller may also insert more than one entry on the queue
with one hcall() using H_SEND_SUB_CRQ_INDIRECT. Use of this hcall()
requires that there be enough space on the queue for all the entries,
otherwise none of the entries are placed onto the Sub-CRQ.</para>
<para>At the receiver&#8217;s option, it may be notified via an interrupt
when an element is enqueued to its Sub-CRQ. See
<xref linkend="dbdoclet.50569348_12194" />.</para>
<para>When the receiver has finished processing a Sub-CRQ entry, it
writes the header to the value 0x00 to invalidate the entry and free it
for future entries.</para>
<para>Should the receiver wish to terminate or reset the communication
channel it deregisters the Sub-CRQ (H_FREE_SUB_CRQ), and if it needs to
re-establish communications, proceeds to register (H_REG_SUB_CRQ) either
the same or different section of memory as the new queue, with the queue
pointers reset to the first entry. Deregistering a CRQ (H_FREE_CRQ) is an
implicit deregistration of any Sub-CRQs associated with the CRQ.</para>
</section>
<section xml:id="dbdoclet.50569348_12194">
<title>Sub-CRQ Facility Interrupt Notification</title>
<para>The receiver can set the virtual interrupt associated with its
Sub-CRQ to one of two modes. These are:</para>
<orderedlist>
<listitem>
<para>Disabled (an enqueued interrupt is not signaled).</para>
</listitem>
<listitem>
<para>Enabled (an enqueued interrupt is signaled on every
enqueue).</para>
</listitem>
</orderedlist>
<para><emphasis role="bold">Note:</emphasis> An enqueue is considered a pulse not a level.
The pulse then sets the memory element within the emulated interrupt
source controller. This allows the resetting of the interrupt condition
by simply issuing the H_EOI hcall() as is done with the PCI MSI
architecture rather than having to do an explicit interrupt reset as in
the case with PCI Level Sensitive Interrupt (LSI) architecture.</para>
<para>The interrupt mechanism is capable of presenting only one interrupt
signal at a time from any given interrupt source. Therefore, no
additional interrupts from a given source are ever signaled until the
previous interrupt has been processed through to the issuance of an H_EOI
hcall(). Specifically, even if the interrupt mode is enabled, the effect
is to interrupt on an empty to non-empty transition of the queue.
However, as with any asynchronous posting operation race conditions are
to be expected. That is, an enqueue can happen in a window around the
H_EOI hcall(). Therefore, the receiver should poll the Sub-CRQ (that is,
look at the header byte of the next queue entry to see if the entry is
valid) after an H_EOI to prevent losing initiative.</para>
<para>The hcall() used to enable and disable this Sub-CRQ interrupt
notification is H_VIO_SIGNAL (see
<emphasis><xref linkend="dbdoclet.50569348_27549" /></emphasis>).</para>
</section>
<section>
<title>Extensions to Other hcall()s for Sub-CRQ</title>
<para />
<section>
<title>H_MIGRATE_DMA</title>
<para>Since Sub-CRQs are RTCE table mapped, the H_MIGRATE_DMA hcall() may
be requested to move a page that is part of a Sub-CRQ. The OS owner of
the queue is responsible for preventing its processors from modifying the
page during the migrate operation (as is standard practice with this
hcall()), however, the H_MIGRATE_DMA hcall() serializes with the Sub-CRQ
hcall()s to direct new elements to the migrated target page.</para>
</section>
<section>
<title>H_XIRR, H_EOI</title>
<para>The Sub-CRQ facility utilizes a virtual interrupt source number to
notify the queue owner of new element enqueues. The standard H_XIRR and
H_EOI hcall()s are extended to support this virtual interrupt mechanism,
emulating the standard PowerPC Interrupt hardware with respect to the
virtual interrupt source number.</para>
</section>
</section>
<section xml:id="sec_subcrq_req">
<title>Sub-CRQ Facility Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility:</emphasis> The platform must implement
the Sub-CRQ as specified in
<xref linkend="dbdoclet.50569348_98947" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_99234">
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility:</emphasis>
The platform must
start enqueueing Commands/Responses to the newly registered Sub-CRQ
starting at offset zero and proceeding as in a circular buffer, each
entry being 32 byte aligned.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_57888">
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility:</emphasis>
The platform must
enqueue Commands/Responses only if the 32 byte entry is free (header byte
contains 0x00), else the enqueue operation fails.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility:</emphasis> The first byte of a Sub-CRQ
entry must be the Header byte and must be as defined in
<xref linkend="dbdoclet.50569348_26980" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility option:</emphasis> Platforms that
implement the H_MIGRATE_DMA hcall() must implement that function for
pages mapped for use by the Sub-CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_req"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Sub-CRQ facility:</emphasis> The platforms must emulate
the standard PowerPC External Interrupt Architecture for the interrupt
source numbers associated with the virtual devices via the standard RTAS
and hypervisor interrupt calls and must extend H_XIRR and H_EOI hcall()s
as appropriate for Sub-CRQ interrupts.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569348_51946">
<title>Partition Managed Class - Synchronous
Infrastructure</title>
<para>The architectural intent of the Synchronous VIO infrastructure is
for platforms where the communicating partitions are under the control of
the same hypervisor. Operations between the partitions are via
synchronous hcall() operations. The Synchronous VIO infrastructure
defines three options:</para>
<itemizedlist>
<listitem>
<para>Reliable Command/Response Transport option (see
<xref linkend="dbdoclet.50569348_48491" /></para>
</listitem>
<listitem>
<para>Subordinate CRQ Transport option (see
<xref linkend="dbdoclet.50569348_28179" /></para>
</listitem>
<listitem>
<para>Logical Remote DMA (LRDMA) option (see
<xref linkend="dbdoclet.50569348_61656" />)</para>
</listitem>
</itemizedlist>
<section xml:id="dbdoclet.50569348_48491">
<title>Reliable Command/Response Transport Option</title>
<para>For the synchronous infrastructure, the CRQ facility defined in
<emphasis><xref linkend="dbdoclet.50569348_98947" /></emphasis> is
implemented via the Reliable Command/Response Transport
option. The synchronous nature of this infrastructure allows for the
capability to immediately (synchronously) notify the sender of the
message whether the message was delivered successfully or not.</para>
<section xml:id="dbdoclet.50569348_13013">
<title>Reliable CRQ Format and Registration</title>
<para>The format of the CRQ is as defined in
<xref linkend="dbdoclet.50569348_98947" />.</para>
<para>The I/O address and length of the queue are registered using the
H_REG_CRQ hcall().
<xref linkend="dbdoclet.50569348_96691" />.</para>
</section>
<section xml:id="dbdoclet.50569348_20229">
<title>Reliable CRQ Entry Format</title>
<para>See
<xref linkend="dbdoclet.50569348_54982" />.</para>
</section>
<section xml:id="dbdoclet.50569348_99091">
<title>Reliable CRQ Entry Processing</title>
<para>A sender uses the H_SEND_CRQ hcall() to enter a 16 byte message on
its partner&#8217;s queue. The hcall() takes the entire message as input
parameters in two registers.
<xref linkend="dbdoclet.50569348_67318" />.</para>
</section>
<section xml:id="dbdoclet.50569348_51715">
<title>Reliable Command/Response Transport Interrupt
Notification</title>
<para>The receiver can enable and disable the virtual interrupt
associated with its CRQ. See
<xref linkend="dbdoclet.50569348_27549" />.</para>
</section>
<section xml:id="dbdoclet.50569348_36248">
<title>Reliable Command/Response Transport hcall()s</title>
<para>The H_REG_CRQ and H_FREE_CRQ hcall()s are used by both client and
server virtual IOA device drivers. It is the architectural intent that
the hypervisor maintains a connection control structure for each defined
partner/server connection. The H_REG_CRQ and its corresponding H_FREE_CRQ
register and deregister partition resources with that connection control
structure. However, there are several conditions that can arise
architecturally with this connection process (the design of an
implementation may preclude some of these conditions).</para>
<itemizedlist>
<listitem>
<para>The association connection to the partner virtual IOA not being
defined (H_Not_Found). The CRQ registration function fails if the CRQ is
not registered with the hypervisor.</para>
</listitem>
<listitem>
<para>The partner virtual IOA may not have registered its CRQ
(H_Closed). The CRQ is registered with the hypervisor and the connection.
However, the connection is incomplete because their partner has not
registered.</para>
</listitem>
<listitem>
<para>The partner virtual IOA may be already connected to another
partner virtual IOA (H_Resource). The CRQ registration function fails if
the CRQ is not registered with the hypervisor or the connection.</para>
</listitem>
</itemizedlist>
<para>The reaction of the virtual IOA device driver to these conditions
is somewhat different depending upon the calling device driver being for
a client or server IOA. Server IOAs in many cases register prior to their
partner IOAs since they are servers and subsequently wait for service
requests from their clients. Therefore, the H_Closed return code is to be
expected when the DD&#8217;s CRQ has been registered with the connection
and is just waiting for the partner to register. Should a partner DD
register its CRQ in the future, higher level protocol messages (via the
Initialization Command/Response CRQ entry) can notify the server DD when
the connection is established. If a client IOA registers and receives a
return code of H_Closed, it may choose to deregister the CRQ and fail
since the client IOA would not be in a position to successfully send
service requests using the CRQ facility, or it may wait and rely upon
higher level CRQ messages (via the Initialization Command/Response CRQ
entry) to tell it when its partner has registered. The reaction of a
virtual IOA DDs to H_Not_Found and H_Resource are dependent upon the
functionality of higher level platform and system management policies.
While the current registration has failed, higher level system and or
platform management actions may allow a future registration request to
succeed.</para>
<para>When registration succeeds, an association is made between the
partner partition&#8217;s LIOBN (RTCE table) and the second window pane
of the server partition. This association is dropped when either partner
deregisters or terminates. However, on deregistration or termination, the
RTCE tables associated with the local partition (first window pane)
remain intact for that partition (see Requirement
<xref linkend="dbdoclet.50569348_77308" />).</para>
<section xml:id="dbdoclet.50569348_96691">
<title>H_REG_CRQ</title>
<para>This hcall() registers the RTCE table mapped memory that contains
the CRQ.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: Failed due to Invalid Parameter */
/* H_Not_Found: Failed due to undefined partner connection.*/
/* H_Closed: Registration completed partner not connected. */
/* H_Resource: Failed due to busy connection to partner. */
hcall ( const int64 H_REG_CRQ, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 queue, /* I/O address of a receive queue (4 KB aligned) */
uint64 len /* Length of the receive queue (multiple of 4 KB) */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>queue: I/O address (offset into the RTCE table) of the CRQ buffer
(starting on a 4 KB boundary).</para>
</listitem>
<listitem>
<para>len: Length of the CRQ in bytes (a multiple of 4 KB)</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate unit-address, else H_Parameter</para>
</listitem>
<listitem>
<para>Validate queue, which is the I/O address of the CRQ (I/O
addresses for entire buffer length starting at the specified I/O address
are translated by the RTCE table, is 4 KB aligned, and length, len, is a
multiple of 4 KB), else H_Parameter</para>
</listitem>
<listitem>
<para>Validate that there is an authorized connection to another
partition associated with the Unit Address, else H_Not_Found.</para>
</listitem>
<listitem>
<para>Validate that the authorized connection to another partition
associated with the Unit Address is free, else H_Resource.</para>
</listitem>
<listitem>
<para>Initialize the CRQ enqueue pointer and length variables. These
variables are kept in terms of I/O addresses so that page migration works
and any remapping of TCEs is effective.</para>
</listitem>
<listitem>
<para>Disable CRQ interrupts.</para>
</listitem>
<listitem>
<para>Allow for Logical Remote DMA, when applicable, with associated
partner partition when partner registers.</para>
</listitem>
<listitem>
<para>If partner is already registered, then return H_Success, else
return H_Closed.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_96323">
<title>H_FREE_CRQ</title>
<para>This hcall() deregisters the RTCE table mapped memory that contains
the CRQ. In addition, if there are any Sub-CRQs associated with the CRQ,
the H_FREE_CRQ has the effect of releasing the Sub-CRQs.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Resource, H_Hardware, H_Busy, */
/* H_LongBusyOrder1mSec, H_LongBusyOrder10mSec,*/
hcall ( const int64 H_FREE_CRQ, /* Function Code */
uint64 unit-address /* As specified in the Virtual IOA's device tree node */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate unit-address, else H_Parameter</para>
</listitem>
<listitem>
<para>Mark the connection to the associated partner partition as closed
(so that send hcall()s from the partner partition fail).</para>
</listitem>
<listitem>
<para>Mark the CRQ enqueue pointer and length variables as
invalid.</para>
</listitem>
<listitem>
<para>For any and all Sub-CRQs associated with the CRQ, do the
following:</para>
<itemizedlist>
<listitem>
<para>Mark the connection to the associated partner partition as closed
for the Sub-CRQ (so that send hcall()s from the partner partition
fail).</para>
</listitem>
<listitem>
<para>Mark the Sub-CRQ enqueue pointer and length variables for the
Sub-CRQ as invalid.</para>
</listitem>
<listitem>
<para>Disable Sub-CRQ interrupts for the Sub-CRQ.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Disable CRQ interrupts.</para>
</listitem>
<listitem>
<para>If there exists any Redirected TCEs in the local TCE tables
associated with this Virtual IOA, and all of those tables have a Bit
Bucket Allowed attribute of 1, then Disable Logical Remote DMA with
associated partner partition, if enabled, invalidating any Redirected
TCEs in the local TCE tables (for information on invalidation of TCEs,
see <xref linkend="dbdoclet.50569348_69987" />).</para>
</listitem>
<listitem>
<para>If there exists any Redirected TCEs in the local TCE tables
associated with this Virtual IOA, and any of those tables have a Bit
Bucket Allowed attribute of 0, then return H_Resource or perform some
other platform-specific error recovery.</para>
</listitem>
<listitem>
<para>Send partner terminated message to partner queue (if it is still
registered), overlaying the last valid entry in the queue if the CRQ is
full.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> If the hypervisor returns an
H_Busy, H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, software must
call H_FREE_CRQ again with the same parameters. Software may choose to
treat H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy.
The hypervisor, prior to returning H_Busy, H_LongBusyOrder1mSec, or
H_LongBusyOrder10mSec, will have placed the virtual adapter in a state
that will cause it to not accept any new work nor surface any new virtual
interrupts (no new entries will be placed on the CRQ).</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_67318">
<title>H_SEND_CRQ</title>
<para>This hcall() sends one 16 byte entry to the partner
partition&#8217;s registered CRQ.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Dropped, H_Hardware, H_Closed */
hcall ( const int64 H_SEND_CRQ, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 msg-high, /* High order 8 bytes of message starting with the header */
/* and format bytes */
uint64 msg-low /* Low order 8 bytes of message */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-addr: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>msg-high:</para>
<itemizedlist>
<listitem>
<para>header: high order bit is on -- header of value 0xFF is reserved
for transport error and is invalid for input.</para>
</listitem>
<listitem>
<para>format: not checked by the firmware.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>msg-low: not checked by the firmware -- should be consistent with
the definition of the format byte.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address, else return H_Parameter</para>
</listitem>
<listitem>
<para>Validate that the msg header byte has its high order bit on and
that it is not = 0xFF, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that there is an authorized connection to another
partition associated with the Unit Address and that the associated CRQ is
enabled, else return H_Closed.</para>
</listitem>
<listitem>
<para>Enter Critical Section on target CRQ</para>
<itemizedlist>
<listitem>
<para>Validate that there is room on the receive queue for the message
and allocate that message, else exit critical Section and return
H_Dropped.</para>
</listitem>
<listitem>
<para>Store msg-low into the second 8 bytes of the allocated queue
element.</para>
</listitem>
<listitem>
<para>Store order barrier</para>
</listitem>
<listitem>
<para>Store msg-high into the first 8 bytes of the allocated queue
element (setting the header valid bit.)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Exit Critical Section</para>
</listitem>
<listitem>
<para>If receiver queue interrupt mode == enabled, then signal
interrupt</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_43427">
<title>H_ENABLE_CRQ</title>
<para>This hcall() explicitly enables a CRQ that has been disabled due to
a Partner partition suspended transport event. As a side effect of this
hcall(), all pages that are mapped via the logical TCE table associated
with the first pane of
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property of the
associated virtual IOA are restored prior to successful completion of the
hcall(). It is the architectural intent that this hcall() is made while
the logical TCE contains mappings for all the pages that will be involved
in the recovery of the outstanding I/O operations at the time of the
partition migration. Further, it is the architectural intent that this
hcall() is made from a processing context that can handle the expected
busy wait return code without blocking the processor.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: CRQ enabled and TCE mapped pages restored */
/* H_Parameter: Invalid unit-address */
/* H_Hardware: A hardware error prevented the function */
/* H_LongBusyOrder10mSec: wait for asynchronous processing */
/* H_IN_PROGRESS: more processing required to complete -- */
/* call again */
hcall ( const int64 H_ENABLE_CRQ, /* Function Code */
uint64 unit-address /* As specified in the Virtual IOA’s device tree node */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-addr: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address, else return H_Parameter</para>
</listitem>
<listitem>
<para>Test that all pages mapped through the logical TCE table
associated with the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property associated
with the unit-address parameter are present; else return
H_LongBusyOrder10mSec.</para>
</listitem>
<listitem>
<para>Set the status of the CRQ associated with the unit-address
parameter to enabled.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="dbdoclet.50569348_66775">
<title>Reliable Command/Response Transport Option
Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66775"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reliable Command/Response Transport
option:</emphasis> The platform must implement the CRQ facility, as
defined in
<xref linkend="dbdoclet.50569348_98947" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66775"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reliable Command/Response Transport
option:</emphasis> The platform must implement the H_REG_CRQ hcall().
<xref linkend="dbdoclet.50569348_96691" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66775"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reliable Command/Response Transport
option:</emphasis> The platform must implement the H_FREE_CRQ hcall().
<xref linkend="dbdoclet.50569348_96323" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66775"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reliable Command/Response Transport
option:</emphasis> The platform must implement the H_SEND_CRQ hcall().
<xref linkend="dbdoclet.50569348_67318" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_66775"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reliable Command/Response Transport
option:</emphasis> The platform must implement the H_ENABLE_CRQ hcall().
<xref linkend="dbdoclet.50569348_43427" />.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569348_61656">
<title>Logical Remote DMA (LRDMA) Option</title>
<para>The Logical Remote Direct Memory Access (LRDMA) option allows a
server partition to securely target memory pages within a partner
partition for VIO operations.</para>
<para>This architecture defines two modes of RDMA</para>
<itemizedlist>
<listitem>
<para><emphasis>Copy RDMA</emphasis> is used to have the hypervisor copy data
between a buffer in the server partition&#8217;s memory and a buffer in
the partner partition&#8217;s memory. See
<xref linkend="dbdoclet.50569348_15951" /> for more information on Copy
RDMA with respect to LRDMA.</para>
</listitem>
<listitem>
<para><emphasis>Redirected RDMA</emphasis> allows for a server partition to
securely target its I/O adapter's DMA operations directly at the memory
pages of the partner partition. The platform overhead of Copy RDMA is
generally greater than Redirected RDMA, but this overhead may be offset
if the server partition&#8217;s DMA buffer is being used as a data cache
for multiple VIO operations. See
<xref linkend="dbdoclet.50569348_25634" /> for more information on
Redirected RDMA with respect to LRDMA.</para>
</listitem>
</itemizedlist>
<para>The mapping between the LIOBN in the second pane of a server
virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property and the
corresponding partner IOA&#8217;s RTCE table is made when the CRQ
successfully completes registration. The partner partition is not aware
if the server partition is using Copy RDMA or Redirected RDMA. The server
partition uses the Logical RDMA mode that best suits its needs for a
given VIO operation. See
<xref linkend="dbdoclet.50569348_40629" /> for more information on RTCE
tables.</para>
<section xml:id="dbdoclet.50569348_15951">
<title>Copy RDMA</title>
<para>The Copy RDMA hcall()s are used to request that the hypervisor move
data between partitions. The specific implementation is optimized to the
platform&#8217;s hardware features. There are calls for when both source
and destination buffers are RTCE table mapped (H_COPY_DMA) and when only
the remote buffers are mapped (H_WRITE_RDMA and H_READ_RDMA).</para>
<section xml:id="dbdoclet.50569348_43271">
<title>H_COPY_RDMA</title>
<para>This hcall() copies data from an RTCE table mapped buffer in one
partition to an RTCE table mapped buffer in another partition, with the
length of the transfer being specified by the transfer length parameter
in the hcall(). The
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis> property, if
it exists (in the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> (node), specifies the maximum length of the
transfer (minimum value of this property is 128 KB).</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_S_Parm, H_D_Parm, H_Permission, */
/* H_Hardware */
hcall ( const uint64 H_COPY_RDMA, /* Performs Copy RDMA */
int64 len, /* Length of transfer */
uint64 s-liobn, /* LIOBN (RTCE table handle) of V-DMA source buffer */
uint64 s-ioba, /* IO address of V-DMA source buffer */
uint64 d-liobn, /* LIOBN (RTCE table handle) of V-DMA destination buffer */
uint64 d-ioba /* I/O address of V-DMA destination buffer */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>len: Length of transfer (length not to exceed the value in the
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis> property, if
it exists)</para>
</listitem>
<listitem>
<para>s-liobn: LIOBN (RTCE table handle) of V-DMA source buffer</para>
</listitem>
<listitem>
<para>s-ioba: IO address of V-DMA source buffer</para>
</listitem>
<listitem>
<para>d-liobn: LIOBN (RTCE table handle) of V-DMA destination
buffer</para>
</listitem>
<listitem>
<para>d-ioba: I/O address of V-DMA destination buffer</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Serialize access to RTCE tables with H_MIGRATE_DMA.</para>
</listitem>
<listitem>
<para>If the
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis> property exist
in the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node of the device tree, then if the value
of len is greater than the value of this property, return
H_Parameter.</para>
</listitem>
<listitem>
<para>Source and destination LIOBNs are checked for authorization per
the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_S_Parm or H_D_Parm, respectively.</para>
</listitem>
<listitem>
<para>Source and destination ioba&#8217;s and length are checked for
valid ranges per the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_S_Parm or H_D_Parm, respectively.</para>
</listitem>
<listitem>
<para>The access bits of the associated TCEs are checked for
authorization, else return H_Permission.</para>
</listitem>
<listitem>
<para>Copy len number of bytes from the buffer starting at the
specified source address to the buffer starting at the specified
destination address, then return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_55103">
<title>H_WRITE_RDMA</title>
<para>This hcall() copies up to 48 bytes of data from a set of input
parameters to an RTCE table mapped buffer in another partition.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_D_Parm, H_Permission, */
/* H_Hardware */
hcall ( const uint64 H_WRITE_RDMA, /* Performs Copy RDMA */
int64 len, /* Length of transfer */
uint64 d-liobn, /* LIOBN (RTCE table handle) of V-DMA destination buffer */
uint64 d-ioba, /* I/O address of V-DMA destination buffer */
uint64 data1, /* The source data is provided via input parameters */
uint64 data2,
uint64 data3,
uint64 data4,
uint64 data5,
uint64 data6);
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>len: Length of transfer</para>
</listitem>
<listitem>
<para>d-liobn: LIOBN (RTCE table handle) of V-DMA destination
buffer</para>
</listitem>
<listitem>
<para>d-ioba: I/O address of V-DMA destination buffer</para>
</listitem>
<listitem>
<para>data1: Source data</para>
</listitem>
<listitem>
<para>data2: Source data</para>
</listitem>
<listitem>
<para>data3: Source data</para>
</listitem>
<listitem>
<para>data4: Source data</para>
</listitem>
<listitem>
<para>data5: Source data</para>
</listitem>
<listitem>
<para>data6: Source data</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Check that the len parameter =&gt; 0 and &lt;= 48, else return
H_Parameter</para>
</listitem>
<listitem>
<para>The destination LIOBN is checked for authorization per the remote
triple of the one of the calling partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_D_Parm.</para>
</listitem>
<listitem>
<para>The destination ioba and length are check for valid ranges per
the remote triple of the one of the calling partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_D_Parm.</para>
</listitem>
<listitem>
<para>Serialize access to the destination RTCE table with
H_MIGRATE_DMA.</para>
</listitem>
<listitem>
<para>The access bits of the associated RTCE table TCEs are checked for
authorization, else return H_Permission.</para>
</listitem>
<listitem>
<para>Copy len number of bytes from the data parameters starting at the
high order byte of data1 toward the low order byte of data 6 into the
buffer starting at the specified destination address, then return
H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_34894">
<title>H_READ_RDMA</title>
<para>This hcall() copies up to 72 bytes of data from an RTCE table
mapped buffer into a set of return registers.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_S_Parm, H_Permission, */
/* H_hardware */
hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */
int64 len, /* Length of transfer */
uint64 s-liobn, /* LIOBN (RTCE table handle) of V-DMA source buffer */
uint64 s-ioba /* IO address of V-DMA source buffer */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>len: Length of transfer</para>
</listitem>
<listitem>
<para>s-liobn: LIOBN (RTCE table handle) of V-DMA source buffer</para>
</listitem>
<listitem>
<para>s-ioba: IO address of V-DMA source buffer</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Check that the len parameter =&gt; 0 and &lt;= 72, else return
H_Parameter</para>
</listitem>
<listitem>
<para>The source LIOBN is checked for authorization per the remote
triple of the one of the calling partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_S_Parm.</para>
</listitem>
<listitem>
<para>The source ioba and length are check for valid ranges per the
remote triple of the one of the calling partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property, else return
H_S_Parm.</para>
</listitem>
<listitem>
<para>Serialize access to the source RTCE table with
H_MIGRATE_DMA.</para>
</listitem>
<listitem>
<para>The access bits of the associated RTCE table TCEs are checked for
authorization, else return H_Permission.</para>
</listitem>
<listitem>
<para>Copy len number of bytes from the source data buffer specified by
s-liobn starting at s-ioba, into the registers R4 through R12 starting
with the high order byte of R4 toward the low order byte of R12, then
return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="dbdoclet.50569348_58889">
<title>Logical Remote DMA Option Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_58889"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Logical Remote DMA option:</emphasis> The platform must
implement the H_PUT_RTCE hcall() as specified in
<xref linkend="dbdoclet.50569348_96734" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_58889"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Logical Remote DMA option:</emphasis> The platform must
implement the extensions to the H_PUT_TCE hcall() as specified in
<xref linkend="dbdoclet.50569348_15493" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_58889"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Logical Remote DMA option:</emphasis> The platform must
implement the extensions to the H_MIGRATE_DMA hcall() as specified in
<xref linkend="dbdoclet.50569348_15120" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_58889"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Logical Remote DMA option:</emphasis> The platform must
implement the H_COPY_RDMA hcall() as specified in
<xref linkend="dbdoclet.50569348_43271" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569348_56403">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569348_58889"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Logical Remote DMA option:</emphasis>
The platform must
disable Logical Remote DMA operations that target an inactive partition
(one that has terminated), including the H_COPY_RDMA hcall() and the
H_PUT_RTCE hcall().</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis role="bold">Implementation Note:</emphasis> It is expected that as part of
meeting Requirement
<xref linkend="dbdoclet.50569348_56403" />, all of the terminating
partition&#8217;s TCE table entries (regular and RTCE) are invalidated
along with any clones (for information on invalidation of TCEs, see
<xref linkend="dbdoclet.50569348_69987" />). While other mechanisms are
available for meeting this requirement in the case of H_COPY_RDMA, this
is the only method for Redirected RDMA, and since it works in both cases,
it is expected that implementations will use this single
mechanism.</para>
</section>
</section>
<section xml:id="dbdoclet.50569348_28179">
<title>Subordinate CRQ Transport Option</title>
<para>For the synchronous infrastructure, in addition to the CRQ facility
defined in
<emphasis><xref linkend="dbdoclet.50569348_98947" /></emphasis>,
the Subordinate CRQ Transport option may also be implemented
in conjunction with the CRQ facility. That is, the Subordinate CRQ
Transport option requires that the Reliable Command/Response Transport
option also be implemented. For this option, the Sub-CRQ facility defined
in
<emphasis><xref linkend="dbdoclet.50569348_92689" /></emphasis> is
implemented.</para>
<section xml:id="dbdoclet.50569348_10878">
<title>Sub-CRQ Format and Registration</title>
<para>The format of the Sub-CRQ is as defined in
<xref linkend="dbdoclet.50569348_92689" />.</para>
<para>The I/O address and length of the queue are registered using the
H_REG_SUB_CRQ hcall().
<xref linkend="dbdoclet.50569348_63838" />.</para>
</section>
<section>
<title>Sub-CRQ Entry Format</title>
<para>See
<xref linkend="dbdoclet.50569348_78758" />.</para>
</section>
<section>
<title>Sub-CRQ Entry Processing</title>
<para>A sender uses the H_SEND_SUB_CRQ or H_SEND_SUB_CRQ_INDIRECT hcall()
to enter one or more 32 byte messages on its partner&#8217;s queue.
<xref linkend="dbdoclet.50569348_62703" /> and
<xref linkend="dbdoclet.50569348_16926" />.</para>
</section>
<section>
<title>Sub-CRQ Transport Interrupt Notification</title>
<para>The receiver can enable and disable the virtual interrupt
associated with its Sub-CRQ using the H_VIOCTL hcall(), with the
appropriate subfunction. See
<xref linkend="dbdoclet.50569348_33176" />. The interrupt number that is
used in the H_VIOCTL call is obtained from the H_REG_SUB_CRQ call that is
made to register the Sub-CRQ.</para>
</section>
<section>
<title>Sub-CRQ Transport hcall()s</title>
<para>The H_REG_SUB_CRQ and H_FREE_SUB_CRQ hcall()s are used by both
client and server virtual IOA device drivers. It is the architectural
intent that the hypervisor maintains a connection control structure for
each defined partner/server connection. The H_REG_SUB_CRQ and its
corresponding H_FREE_SUB_CRQ register and deregister partition resources
with that connection control structure. However, there are several
conditions that can arise architecturally with this connection process
(the design of an implementation may preclude some of these
conditions).</para>
<itemizedlist>
<listitem>
<para>The association connection to the partner virtual IOA not being
defined (H_Not_Found).</para>
</listitem>
<listitem>
<para>The partner virtual IOA CRQ connection may not have been
completed (H_Closed).</para>
</listitem>
<listitem>
<para>The partner may deregister its CRQ which also deregisters any
associated Sub-CRQs.</para>
</listitem>
</itemizedlist>
<section xml:id="dbdoclet.50569348_63838">
<title>H_REG_SUB_CRQ</title>
<para>This hcall() registers the RTCE table mapped memory that contains
the Sub-CRQ. Multiple Sub-CRQ registrations may be attempted for each
virtual IOA. If resources are not available to establish a Sub-CRQ, the
H_REG_SUB_CRQ call will fail with H_Resource.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this hcall() might change, and the caller should be prepared to receive
an H_Function return code indicating the platform does not implement this
hcall(). If a virtual IOA exists in the device tree after migration that
requires by this architecture the presence of this hcall(), then if that
virtual IOA exists after the migration, it can be expected that the
hcall() will, also.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Registration completed */
/* H_Parameter: Failed due to Invalid Parameter */
/* H_Not_Found: Failed due to undefined partner connection.*/
/* H_Closed: Registration completed partner (CRQ) not */
/* connected. */
/* H_Resource: Failed due to lack of resources. */
/* H_Hardware: Function failed due to hardware error */
hcall ( const int64 H_REG_SUB_CRQ, /* Returns in R4 a cookie representing */
/* the Sub-CRQ number */
/* Returns in R5 the interrupt number */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 Sub-CRQ-ioba, /* I/O address of a Sub-CRQ (4 KB aligned)*/
uint64 Sub-CRQ-length /* Length of the Sub-CRQ (multiple of 4 KB) */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Sub-CRQ-ioba: I/O address (offset into the RTCE table, as
specified by the first window pane of the virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property) of the
Sub-CRQ buffer (starting on a 4 KB boundary).</para>
</listitem>
<listitem>
<para>Sub-CRQ-length: Length of the Sub-CRQ in bytes (a multiple of 4
KB).</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate unit-address, else H_Parameter.</para>
</listitem>
<listitem>
<para>Validate Sub-CRQ-ioba, which is the I/O address of the Sub-CRQ
(I/O addresses for entire buffer length starting at the specified I/O
address are translated by the RTCE table, is 4 KB aligned, and length,
Sub-CRQ-length, is a multiple of 4 KB), else H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that there are sufficient resources associated with the
Unit Address to allocate the Sub-CRQ, else H_Resource.</para>
</listitem>
<listitem>
<para>Initialize the Sub-CRQ enqueue pointer and length variables.
These variables are kept in terms of I/O addresses so that page migration
works and any remapping of TCEs is effective.</para>
</listitem>
<listitem>
<para>Initialize all Sub-CRQ entry header bytes to 0 (invalid).</para>
</listitem>
<listitem>
<para>Disable Sub-CRQ interrupts.</para>
</listitem>
<listitem>
<para>Place cookie representing Sub-CRQ number (will be used in
H_SEND_SUB_CRQ, H_SEND_SUB_CRQ_INDIRECT, and H_FREE_SUB_CRQ) in
R4.</para>
</listitem>
<listitem>
<para>Place interrupt number (the same as will be returned by H_XIRR or
H_IPOLL for the interrupt from this Sub-CRQ) in R5.</para>
</listitem>
<listitem>
<para>If the CRQ connection is already complete, then return H_Success,
else return H_Closed.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_39734">
<title>H_FREE_SUB_CRQ</title>
<para>This hcall() deregisters the RTCE table mapped memory that contains
the Sub-CRQ. Note that the H_FREE_CRQ hcall() also deregisters any
Sub-CRQs associated with the CRQ being deregistered by that
hcall().</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this hcall() might change, and the caller should be prepared to receive
an H_Function return code indicating the platform does not implement this
hcall(). If a virtual IOA exists in the device tree after migration that
requires by this architecture the presence of this hcall(), then if that
virtual IOA exists after the migration, it can be expected that the
hcall() will, also.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware, H_Busy, */
/* H_LongBusyOrder1mSec, H_LongBusyOrder10mSec */
hcall ( const int64 H_FREE_SUB_CRQ, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 Sub-CRQ-num /* The Sub-CRQ # cookie returned from H_REG_SUB_CRQ */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Sub-CRQ-num: The queue # cookie returned from H_REG_SUB_CRQ
hcall() at queue registration time.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate unit-address and Sub-CRQ-num, else H_Parameter</para>
</listitem>
<listitem>
<para>Mark the connection to the associated partner partition as closed
for the specified Sub-CRQ (so that send hcall()s from the partner
partition fail).</para>
</listitem>
<listitem>
<para>Mark the Sub-CRQ enqueue pointer and length variables for the
specified Sub-CRQ as invalid.</para>
</listitem>
<listitem>
<para>Disable Sub-CRQ interrupts for the specified Sub-CRQ.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_62703">
<title>H_SEND_SUB_CRQ</title>
<para>This hcall() sends one 32 byte entry to the partner
partition&#8217;s registered Sub-CRQ.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this hcall() might change, and the caller should be prepared to receive
an H_Function return code indicating the platform does not implement this
hcall(). If a virtual IOA exists in the device tree after migration that
requires by this architecture the presence of this hcall(), then if that
virtual IOA exists after the migration, it can be expected that the
hcall() will, also.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Dropped, H_Hardware, H_Closed */
hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 Sub-CRQ-num /* The Sub-CRQ# cookie from H_REG_SUB_CRQ (from partner) */
uint64 msg-dword0, /* High order 8 bytes of message starting with the */
/* header byte */
uint64 msg-dword1, /* Next 8 bytes of message */
uint64 msg-dword2, /* Next 8 bytes of message */
uint64 msg-dword3 /* Low order 8 bytes of message */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-addr: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Sub-CRQ-num: The queue # cookie returned from H_REG_SUB_CRQ
hcall() at queue registration time.</para>
</listitem>
<listitem>
<para>msg-dword0: firmware checks only high order byte.</para>
</listitem>
<listitem>
<para>msg-dword1, msg-dword2, msg-dword3: the rest of the message;
firmware does not validate.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the Sub-CRQ, as specified by Sub-CRQ-num, is
properly registered by the partner, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the message header byte (high order byte of
msg-dword0) is 0x80, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that there is an authorized CRQ connection to another
partition associated with the Unit Address and that the associated CRQ is
enabled, else return H_Closed.</para>
</listitem>
<listitem>
<para>Enter Critical Section on target Sub-CRQ.</para>
<itemizedlist>
<listitem>
<para>Validate that there is room on the specified Sub-CRQ for the
message and allocate that message, else exit critical Section and return
H_Dropped.</para>
</listitem>
<listitem>
<para>Store msgdword1 into bytes 4-7 of the allocated queue
element.</para>
</listitem>
<listitem>
<para>Store msgdword2 into bytes 8-11 of the allocated queue
element.</para>
</listitem>
<listitem>
<para>Store msgdword3 into bytes 12-15 of the allocated queue
element.</para>
</listitem>
<listitem>
<para>Store order barrier.</para>
</listitem>
<listitem>
<para>Store msgdword0 into bytes 0-3 of the allocated queue element
(this sets the valid bit in the header byte).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Exit Critical Section.</para>
</listitem>
<listitem>
<para>If receiver queue interrupt mode is enabled, then signal
interrupt.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569348_16926">
<title>H_SEND_SUB_CRQ_INDIRECT</title>
<para>This hcall() sends one or more 32 byte entries to the partner
partition&#8217;s registered Sub-CRQ. On H_Success, all of the entries
have been put onto the Sub-CRQ. On any return code other than H_Success,
none of the entries have been put onto the Sub-CRQ.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
partition migration option, after partition migration the support for
this hcall() might change, and the caller should be prepared to receive
an H_Function return code indicating the platform does not implement this
hcall(). If a virtual IOA exists in the device tree after migration that
requires by this architecture the presence of this hcall(), then if that
virtual IOA exists after the migration, it can be expected that the
hcall() will, also. The maximum num-entries has increased on some platforms
from 16 to 128. On platforms that implement the partition migration option,
after partition migration the support for this hcall() might change, and the
caller should be prepared to receive an H_Parameter return code in the situation
where more than 16 num-entries have been sent, indicating the platform does not
support more than 16 num-entries.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Dropped, H_Hardware, H_Closed */
hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 Sub-CRQ-num /* The Sub-CRQ# cookie from H_REG_SUB_CRQ (from partner) */
uint64 ioba, /* Address of buffer containing queue entries to be sent */
uint64 num-entries /* Number of queue entries in the buffer to be sent */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-addr: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>Sub-CRQ-num: The Sub-CRQ # cookie returned from H_REG_SUB_CRQ
hcall() at queue registration time.</para>
</listitem>
<listitem>
<para>ioba: The address of the TCE-mapped page which contains the
entries to be placed onto the specified Sub-CRQ.</para>
</listitem>
<listitem>
<para>num-entries: Number of entries to be placed onto the specified
Sub-CRQ from the TCE mapped page starting at ioba (maximum number of
entries is 16 in order to minimize the hcall() time).</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that the Sub-CRQ, as specified by Sub-CRQ-num, is
properly registered by the partner, else return H_Parameter.</para>
</listitem>
<listitem>
<para>If ioba is outside of the range of the calling partition assigned
values, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If num-entries is not in the range of 1 to 128, then return
H_Parameter.</para>
</listitem>
<listitem>
<para>If num-entries is not in the range of 1 to 16, then return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that there is an authorized CRQ connection to another
partition associated with the Unit Address and that the associated CRQ is
enabled, else return H_Closed.</para>
</listitem>
<listitem>
<para>Copy (num-entries * 32) bytes from the page specified starting at
ioba to a temporary hypervisor page for contents verification and
processing (this avoids the problem of the caller changing call by
reference values after they are checked).</para>
</listitem>
<listitem>
<para>Validate that the message header bytes for num-entries starting
at ioba are 0x80, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Enter Critical Section on target Sub-CRQ.</para>
<itemizedlist>
<listitem>
<para>Validate that there is room on the specified Sub-CRQ for
num-entries messages and allocate those messages, else exit critical
Section and return H_Dropped.</para>
</listitem>
<listitem>
<para>For each of the num-entries starting at ioba</para>
<itemizedlist>
<listitem>
<para>Store entry bytes 1-31 into bytes 1-31 of the allocated queue
element.</para>
</listitem>
<listitem>
<para>Store order barrier.</para>
</listitem>
<listitem>
<para>Store entry byte 0 into bytes 0 of the allocated queue element
(this sets the valid bit in the header byte).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Loop</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Exit Critical Section.</para>
</listitem>
<listitem>
<para>If receiver queue interrupt mode is enabled, then signal
interrupt.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="sec_subcrq_transport">
<title>Subordinate CRQ Transport Option Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the Reliable Command/Response Transport option,
as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the Sub-CRQ facility, as defined in
<xref linkend="dbdoclet.50569348_92689" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the H_REG_SUB_CRQ hcall().
<xref linkend="dbdoclet.50569348_63838" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the H_FREE_SUB_CRQ hcall().
<xref linkend="dbdoclet.50569348_39734" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the H_SEND_SUB_CRQ hcall().
<xref linkend="dbdoclet.50569348_62703" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement the H_SEND_SUB_CRQ_INDIRECT hcall().
<xref linkend="dbdoclet.50569348_16926" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_subcrq_transport"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Subordinate CRQ Transport option:</emphasis> The
platform must implement all of the following subfunctions of the H_VIOCTL
hcall() (
<xref linkend="dbdoclet.50569348_33176" />):</para>
<itemizedlist>
<listitem>
<para>DISABLE_ALL_VIO_INTERRUPTS</para>
</listitem>
<listitem>
<para>DISABLE_VIO_INTERRUPT</para>
</listitem>
<listitem>
<para>ENABLE_VIO_INTERRUPT</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- FIXME: Why the empty sections? Something missing? >
<section>
<title> &#160;</title>
<para>&#160;</para>
<para>&#160;</para>
</section>
<section xml:id="dbdoclet.50569348_44496">
<title> &#160;</title>
<para/>
</section-->
</section>
</section>
</section>
<section xml:id="dbdoclet.50569350_23147">
<title>Interpartition Logical LAN (ILLAN) Option</title>
<para>The Interpartition Logical LAN (ILLAN) option provides the
functionality of IEEE VLAN between LPAR partitions. Partitions are
configured to participate in the ILLAN. The participating partitions have
one or more logical IOAs in their device tree.</para>
<para>The hypervisor emulates the functionality of an IEEE VLAN switch.
That functionality is defined in IEEE 802.1Q. The following information on
IEEE VLAN switch functionality is provided for informative reference only
with the referenced document being normative. Logical Partitions may have
one or more Logical LAN IOA&#8217;s each of which appears to be connected
to one and only one Logical LAN Switch port of the single Logical LAN
Switch implemented by the hypervisor. Each Logical LAN Switch port is
configured (by platform dependent means) as to whether the attached Logical
LAN IOA supports IEEE VLAN headers or not, and the allowable VLAN numbers
that the port may use (a single number if VLAN headers are not supported,
an implementation dependent number if VLAN headers are supported). When a
message arrives at a Logical LAN Switch port from a Logical LAN IOA, the
hypervisor caches the message&#8217;s source MAC address (2nd 6 bytes) to
use as a filter for future messages to the IOA. Then the hypervisor
processes the message differently depending upon whether the port is
configured for IEEE VLAN headers, or not. If the port is configured for
VLAN headers, the VLAN header (bytes offsets 12 and 13 in the message) is
checked against the port&#8217;s allowable VLAN list. If the message
specified VLAN is not in the port&#8217;s configuration, the message is
dropped. Once the message passes the VLAN header check, it passes onto
destination MAC address processing below. If the port is NOT configured for
VLAN headers, the hypervisor (conceptually) inserts a two byte VLAN header
(based upon the port&#8217;s configured VLAN number) after byte offset 11
in the message.</para>
<para>Next, the destination MAC address (first 6 bytes of the message) is
processed by searching the table of cached MAC addresses (built from
messages received at Logical LAN Switch ports see above). If a match for
the MAC address is not found and if there is no Trunk Adapter defined for
the specified VLAN number, then the message is dropped, otherwise if a
match for the MAC address is not found and if there is a Trunk Adapter
defined for the specified VLAN number, then the message is passed on to the
Trunk Adapter. If a MAC address match is found, then the associated switch
port is configured and the allowable VLAN number table is scanned for a
match to the VLAN number contained in the message&#8217;s VLAN header. If a
match is not found, the message is dropped. Next, the VLAN header
configuration of the destination Switch Port is checked, and if the port is
configured for VLAN headers, the message is delivered to the destination
Logical LAN IOA including any inserted VLAN header. If the port is
configured for no VLAN headers, the VLAN header is removed before being
delivered to the destination Logical LAN IOA.</para>
<para>The Logical LAN IOA&#8217;s device tree entry includes
<emphasis role="bold"><literal>Unit Address</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> properties. The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property contains a
LIOBN field that represents the RTCE table used by the Logical IOA. The
Logical LAN hcall()s use the Unit Address field to imply the LIOBN and,
therefore, the RTCE table to reference.</para>
<para>When the logical IOA is opened, the device driver registers, with the
hypervisor, as the &#8220;Buffer List&#8221;, a TCE mapped page of
partition I/O mapped memory that contains the receive buffer descriptors.
These receive buffers are mapped via a TCE mechanism from partition memory
into contiguous I/O DMA space. The first descriptor in the buffer list page
is that of the receive queue buffer. The rest of the descriptors are for a
number of buffer pools organized by increasing size of receive buffer. The
format of the descriptor is a 1 byte control field, 3 byte buffer length,
followed by a 4 byte I/O address. The number of buffer pools is determined
by the device driver (up to an architected maximum of 254). The control
field in all unused descriptors is 0h00. The last 8 bytes are reserved for
statistics.</para>
<para>When a new message is received by the logical IOA, the list of buffer
pools is scanned starting from the second descriptor in the buffer list
looking for the first available buffer that is equal to or greater than the
received message. That buffer is removed from the pool, filled with the
incoming message, and an entry is placed on the receive queue noting the
buffer status, message length, starting data offset, and the buffer
correlator.</para>
<para>The sender of a logical LAN message uses an hcall() that takes as
parameters the Unit Address and a list of up to 6 buffer descriptors
(length, starting I/O address pairs). The sending hcall(), after verifying
the sender owns the Unit Address, correlates the Unit Address with its
associated Logical LAN Switch port and copies the message from the send
buffer(s) into a receive buffer, as described above, for each target
logical LAN IOA that is a member of the specified VLAN. If a given logical
IOA does not have a suitable receive buffer, the message is dropped for
that logical IOA (a return code indicates that one or more destinations did
not receive a message allowing for a reliable datagram service).</para>
<para>The logical LAN facility uses the standard H_GET_TCE and H_PUT_TCE
hcall()s to manage the I/O translations tables along with H_MIGRATE_DMA to
aid in dynamic memory reconfiguration.</para>
<section>
<title>Logical LAN IOA Data Structures</title>
<para>The Logical LAN IOA defines certain data structures as described in
following paragraphs.
<xref linkend="dbdoclet.50569350_60986" /> outlines the
inter-relationships between several of these structures. Since multiple
hcall()s as well as multiple partitions access the same structures,
careful serialization is essential.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> During shutdown or migration of
TCE mapped pages, implementations may choose to atomically maintain,
within a single, two field variable, a usage count of processors
currently sending data through the Logical LAN IOA combined with a
quiesce request set to the processor that is requesting the quiesce (if
no quiesce is requested, the value of this field is some reserved value).
Then a protocol, such as the following, can manage the quiesce of Logical
LAN DMA. A new sender atomically checks the DMA channel management
variable -- spinning if the quiesce field is set and subsequently
incrementing the usage count field when the quiesce variable is not set.
The sender atomically decreases the use count when through with Logical
Remote DMA copying. A quiesce requester, after atomically setting the
quiesce field with its processor number (as in a lock), waits for the
usage count to go to zero before proceeding.</para>
<figure xml:id="dbdoclet.50569350_60986">
<title>Logical LAN IOA Structures</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-55.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-55.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<section xml:id="dbdoclet.50569350_35439">
<title>Buffer Descriptor</title>
<para>The buffer descriptor is an 8 byte quantity, on an 8
byte boundary (so that it can be written atomically). The high order byte
is control, the next 3 bytes consist of a length field of the buffer in
bytes, the low order 4 bytes are a TCE mapped I/O address of the start of
the buffer in I/O address space.</para>
<para>Bit 0 of the control field is the valid indicator, 0 means not
valid and 1 is valid. Bits 2-5 are reserved.</para>
<para>Bit 1 is used in the receive queue descriptor as the valid toggle
if the descriptor specifies the receive queue, else it is reserved. If
the valid toggle is a 0, then the newly enqueued receive buffer
descriptors have a valid bit value of 1, if the valid toggle is a 1, then
the newly enqueued receive buffer descriptors have a valid bit value of
0. The hypervisor flips the value of the valid toggle bit each time it
cycles from the bottom of the receive queue to the top.</para>
<para>Bit 5 is the Large Send Indication bit and indicates that this
packet is a large-send packet. See
<xref linkend="sec_illan_large_send_indication" />
for more information on the usage of this bit.</para>
<para>Bit 6 is the No Checksum bit and indicates that there is no
checksum in this packet. See
<xref linkend="dbdoclet.50569350_53238" /> for more information on the
usage of this bit.</para>
<para>Bit 7 is the Checksum Good bit and indicates that the checksum in
this packet has already been verified. See
<xref linkend="dbdoclet.50569350_53238" /> for more information on the
usage of this bit.</para>
</section>
<section xml:id="dbdoclet.50569350_48856">
<title>Buffer List</title>
<para>This structure is used to record buffer descriptors of various
types used by the Logical LAN IOA. Additionally, running statistics about
the logical LAN adapter are maintained at the end of the structure. It
consists of one 4 KB aligned TCE mapped page. By TCE mapping the page,
the H_MIGRATE_DMA hcall() is capable of migrating this structure.</para>
<para>The first buffer descriptor (at offset 0) contains the buffer
descriptor for the receive queue.</para>
<para>The second buffer descriptor (at offset 8) contains the buffer
descriptor for the MAC multicast filter table.</para>
<para>It is the architectural intent that all subsequent buffer
descriptors in the list head a pool of buffers of a given size. Further,
it is the architectural intent that descriptors are ordered in increasing
size of the buffers in their respective pools. The rest of the
description of the ILLAN option is written assuming this intent. However,
the contents of these descriptors are architecturally opaque, none of
these descriptors are manipulated by code above the architected
interfaces. This allows implementations to select the most appropriate
serialization techniques for buffer enqueue/dequeue, migration, and
buffer pool addition and subsequent garbage collection.</para>
<para>The final 8 bytes in the buffer list is a counter of frames dropped
because there was not a buffer in the buffer list capable of holding the
frame.</para>
</section>
<section xml:id="dbdoclet.50569350_59321">
<title>Receive Queue</title>
<para>The receive queue is a circular buffer used to store received
message descriptors. The device driver sizes the buffer used for the
receive queue in multiples of 16 bytes, starting on an 16 byte boundary
(to allow atomic store operations) with, at least, one more 16 byte entry
than the maximum number of possible outstanding receive buffers. Failure
to have enough receive queue entries, may result in receive messages, and
their buffers being lost since the logical IOA assumes that there are
always empty receive queue elements and does not check. When the device
driver registers the receive queue buffer, the buffer contents should be
all zeros, this insures that the valid bits are all off.</para>
<para>If a message is received successfully, the next 16 byte area
(starting with the area at offset 0 for the first message received after
the registration of the receive queue and looping back to the top after
the last area is used) in the receive queue is written with a message
descriptor as shown in
<xref linkend="dbdoclet.50569350_86266" />. Either the entire entry is
atomically written, or the write order is serialized such that the
control field is globally visible after all other fields are
visible.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569350_86266">
<title>Receive Queue Entry</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="60*" />
<thead valign="middle">
<row>
<entry>
<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>Control</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Bit 0 = the appropriate valid indicator.</para>
<para>Bit 1 = 1 if the buffer contains a valid message. Bit 1 =
0 if the buffer does not contain a valid message, in which case
the device driver recycles the buffer.</para>
<para>Bits 2-4 Reserved.</para>
<para>Bit 5: Large Send Indication bit. If a 1, then this
indicates the packet is a large-send packet.</para>
<para>Bit 6: No Checksum bit. If a 1, then this indicates that
there is no checksum in this packet (see
<xref linkend="dbdoclet.50569350_53238" /> for more information
on the usage of this bit).</para>
<para>Bit 7: Checksum Good bit. If a 1, then this indicates
that the checksum in this packet has already been verified (see
<xref linkend="dbdoclet.50569350_53238" /> for more information
on the usage of this bit).</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Reserved for future use.</para>
</entry>
</row>
<row>
<entry>
<para>Message Offset</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>The byte offset to the start of the received message. The
minimum offset is 8 (to bypass the message correlator field);
larger offsets may be used to allow for optimized data copy
operations.</para>
</entry>
</row>
<row>
<entry>
<para>Message Length</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>The byte length of the received message.</para>
</entry>
</row>
<row>
<entry>
<para>Opaque handle</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Copy of the first 8 bytes contained in the message buffer
as passed by the device driver.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>So that the device driver never has to write into the receive
queue, the VLAN logical IOA alternates the value of the valid bit on each
pass through the receive queue buffer. On the first pass following
registration, the valid bit value is written as a 1, on the next as a
zero, on the third as a 1, and so on. To allow the device driver to
follow the state of the valid bit, the Logical LAN IOA maintains a valid
bit toggle in bit 1 of the receive queue descriptor control byte. The
Logical LAN IOA increments its enqueue pointer after each enqueue. If the
pointer increment (modulo the buffer size) loops to the top, the valid
toggle bit alternates state.</para>
<para>Following the write of the message descriptor, if enqueue
interrupts are enabled and there is not an outstanding interrupt signaled
from the Logical LAN IOA&#8217;s interrupt source number, an interrupt is
signaled.</para>
<para>It is the architectural intent that the first 8 bytes of the buffer
is a device driver supplied opaque handle that is copied into the receive
queue entry. One possible format of the opaque handle is the OS effective
address of the buffer control block that pre-ends the buffer as seen by
the VLAN Logical IOA. Within this control block might be stored the total
length of the buffer, the 8 byte buffer descriptor (used to enqueue this
buffer using the H_ADD_LOGICAL_LAN_BUFFER hcall()) and other control
fields as deemed necessary by the device driver.</para>
<para>When servicing the receive interrupt, it is the architectural
intent that the device driver starts to search the receive queue using a
device driver maintained receive queue service pointer (initially
starting, after buffer registration, at the offset zero of the receive
queue) servicing all receive queue entries with the appropriate valid
bit, until reaching the first invalid receive queue entry. The receive
queue service pointer is also post incremented, modulo the receive queue
buffer length, and the device driver&#8217;s notion of valid bit state is
also toggled/read from the receive queue descriptor&#8217;s valid bit
toggle bit, on each cycle through the circular buffer. After all valid
receive queue entries are serviced, the device driver resets the
interrupt.
<xref linkend="dbdoclet.50569350_53237" />. After the interrupt reset,
the device driver again scans from the new value of the receive queue
service pointer to pick up any entries that may have been enqueued during
the interrupt reset window.</para>
</section>
<section>
<title>MAC Multicast Filter List</title>
<para>This one 4 KB page (aligned on a 4 KB boundary) opaque data
structure is used by firmware to contain multicast filter MAC addresses.
The table is initialized by firmware by the H_REGISTER_LOGICAL_LAN
hcall(). Any modification of this table by the partition software (OS or
device driver) is likely to corrupt its contents which may corrupt/affect
the OS&#8217;s partition but not other partitions, that is, the
hypervisor may not experience significant performance degradation due to
table corruption. However, for the partition that corrupted its filter
list, the hypervisor may deliver multicast address packets that had
previously been requested to be filtered out, or it may fail to deliver
multicast address packets that had been requested to be delivered.</para>
</section>
<section xml:id="dbdoclet.50569350_45114">
<title>Receive Buffers</title>
<para>The Logical LAN firmware requires that the minimum size receive
buffer is 16 bytes aligned on an 4 byte boundary so that stores of
linkage pointer may be atomic. Minimum IP message sizes, and message
padding areas force a larger minimum size buffer.</para>
<para>The first 8 bytes of the receive buffer are reserved for a device
driver defined opaque handle that is written into the receive queue entry
when the buffer is filled with a received message. Firmware never
modifies the first 8 bytes of the receive buffer.</para>
<para>From the time of buffer registration via the
H_ADD_LOGICAL_LAN_BUFFER hcall() until the buffer is posted onto the
receive queue, the entire buffer other than the first 8 bytes are subject
to modification by the firmware. Any modification of the buffer contents,
during this time, by non-firmware code subjects receive data within the
partition to corruption. However, any data corruption caused by errors in
partition code does not escape the offending partition, except to the
extent that the corruption involves the data in Logical LAN send
buffers.</para>
<para>Provisions are incorporated in the receive buffer format for a
beginning pad field to allow firmware to make use of data transfer
hardware that may be alignment sensitive. While the contents of the Pad
fields are undefined, firmware is not allowed to make visible to the
receiver more data than was specifically included by the sender in the
transfer message, so as to avoid a covert channel between the
communicating partitions.</para>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Receive Buffer Format</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" />
<colspec colname="c2" colwidth="30*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" 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>
<emphasis role="bold"><literal>Opaque Handle</literal></emphasis>
</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Per design of the device driver.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>Pad 1</literal></emphasis>
</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>0-L1 cache line size</para>
</entry>
<entry>
<para>This field, containing undefined data, may be included by
the firmware to align data for optimized transfers.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>Message</literal></emphasis>
</para>
</entry>
<entry>
<para>defined by the &#8220;Message Offset&#8221; field of the
Receive Queue Entry</para>
</entry>
<entry>
<para>12-N</para>
</entry>
<entry>
<para>The destination and source MAC address are at the first
two 6 byte fields of the message, followed by the message
payload.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>Pad 2</literal></emphasis>
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>To end of buffer</para>
</entry>
<entry>
<para>Buffer contents after the Message field are
undefined.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section>
<title>Logical LAN Device Tree Node</title>
<para>The Logical LAN device tree node is a child of the
<emphasis role="bold"><literal>vdevice</literal></emphasis> node which itself is a child of
<emphasis role="bold"><literal>/</literal></emphasis> (the root node). There exists one such node for
each logical LAN virtual IOA instance. Additionally, Logical LAN device
tree nodes have associated packages such as obp-tftp and load method as
appropriate to the specific virtual IOA configuration as would the node
for a physical IOA of type network.</para>
<para>Logical IOA&#8217;s intrinsic MAC address -- This number is
guaranteed to be unique within the scope of the Logical LAN.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569350_41555">
<title>Properties of the Logical LAN OF Device Tree
Node</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device name, the value shall be
<emphasis role="bold"><literal>&#8220;l-lan&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device type, the value shall be
<emphasis role="bold"><literal>&#8220;network&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
programming models that are compatible with this virtual IOA,
the value shall include
<emphasis role="bold"><literal>&#8220;IBM,l-lan&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA, the value shall
be of the form defined in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the unit
address (unit ID) associated with this virtual IOA presented as
an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of three values
(LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;local-mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
locally administered MAC addresses are denoted by having the
low order two bits of the high order byte being 0b10.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Initial MAC address (may be changed by
H_CHANGE_LOGICAL_LAN_MAC hcall()). <emphasis role="bold">Note:</emphasis> There have been
requests for a globally unique mac address per logical LAN IOA.
However, the combination of -- that requiring that the platform
ship with an unbounded set of reserved globally unique
addresses -- which clearly cannot work -- plus the availability
of IP routing for external connectivity have overridden those
requests.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,mac-address-filters&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the number of non-broadcast
multicast MAC filters supported by this implementation (between
0 and 255) presented as an encoded array encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall().</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vserver&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying that this is a virtual server
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name specifying that this is a Trunk Adapter.
This property must be provided when the node is a Trunk Adapter
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>This property is required when any of the ILLAN
sub-options are implemented (see
<xref linkend="dbdoclet.50569350_89321" />). The existence of
this property indicates that the H_ILLAN_ATTRIBUTES hcall() is
implemented, and that hcall() is then used to determine which
ILLAN options are implemented.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;supported-network-types&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name as per
<emphasis><xref linkend="dbdoclet.50569387_27008" /></emphasis>.
Reports possible types of &#8220;network&#8221;
the device can support.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;chosen-network-type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name as per
<emphasis><xref linkend="dbdoclet.50569387_27008" /></emphasis>.
Reports the type of &#8220;network&#8221; this
device is supporting.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;max-frame-size&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, to indicate maximum
packet size.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;address-bits&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, to indicate network
address length.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Logical LAN hcall()s</title>
<para>The receiver can set the virtual interrupt associated with its
Receive Queue to one of two modes using the H_VIO_SIGNAL hcall(). These
are:</para>
<orderedlist>
<listitem>
<para>Disabled (An enqueue interrupt is not signaled.)</para>
</listitem>
<listitem>
<para>Enabled (An enqueue interrupt is signaled on every
enqueue)</para>
</listitem>
</orderedlist>
<para><emphasis role="bold">Note:</emphasis> An enqueue is considered a pulse not a level.
The pulse then sets the memory element within the emulated interrupt
source controller. This allows the resetting of the interrupt condition
by simply issuing the H_EOI hcall() as is done with the PCI MSI
architecture rather than having to do an explicit interrupt reset as in
the case with PCI LSI architecture.</para>
<para>The interrupt mechanism, however, is capable of presenting only one
interrupt signal at a time from any given interrupt source. Therefore, no
additional interrupts from a given source are ever signaled until the
previous interrupt has been processed through to the issuance of an H_EOI
hcall(). Specifically, even if the interrupt mode is enabled, the effect
is to interrupt on an empty to non-empty transition of the queue.</para>
<section xml:id="dbdoclet.50569350_38939">
<title>H_REGISTER_LOGICAL_LAN</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware */
hcall ( const unit64 H_REGISTER_LOGICAL_LAN, /*Register structures for the logical */
/* LAN IOA */
uint64 unit-address, /* As specified in the Logical LAN device tree node */
uint64 buf-list, /* I/O address of a 4 KB page (aligned) used to record */
/* registered input buffers */
uint64 rec-queue, /* Buffer descriptor of a receive queue */
uint64 filter-list, /* I/O address of a 4 KB page aligned broadcast MAC */
/* address filter list */
uint64 mac-address /* The receive filter MAC address */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: As specified in the Logical LAN device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>buf-list: I/O address of a 4 KB page (aligned) used to record
registered input buffers</para>
</listitem>
<listitem>
<para>rec-queue: Buffer descriptor of a receive queue, specifying a
receive queue which is a multiple of 16 bytes in length and is 16 byte
aligned</para>
</listitem>
<listitem>
<para>filter-list: I/O address of a 4 KB page aligned broadcast MAC
address filter list</para>
</listitem>
<listitem>
<para>mac-address: The receive filter MAC address</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address else H_Parameter</para>
</listitem>
<listitem>
<para>Validate the I/O addresses of the buf-list and filter-list is in
the TCE and is 4K byte aligned else H_Parameter</para>
</listitem>
<listitem>
<para>Validate the Buffer Descriptor of the receive queue buffer (I/O
addresses for entire buffer length starting at the specified I/O address
are translated by the RTCE table, length is a multiple of 16 bytes, and
alignment is on a 16 byte boundary) else H_Parameter.</para>
</listitem>
<listitem>
<para>Initialize the one page buffer list</para>
</listitem>
<listitem>
<para>Enqueue the receive queue buffer (set valid toggle to 0).</para>
</listitem>
<listitem>
<para>Initialize the hypervisor&#8217;s receive queue enqueue pointer
and length variables for the virtual IOA associated with the Unit
Address. These variables are kept in terms of DMA addresses so that page
migration works and any remapping of TCEs is effective.</para>
</listitem>
<listitem>
<para>Disable receive queue interrupts.</para>
</listitem>
<listitem>
<para>Record the low order 6 bytes of mac-address for filtering future
incoming messages.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_78305">
<title>H_FREE_LOGICAL_LAN</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware, H_Busy, */
/* H_LongBusyOrder1mSec, H_LongBusyOrder10mSec */
hcall ( const uint64 H_FREE_LOGICAL_LAN, /*Deregister structures for the logical */
/* LAN IOA*/
uint64 unit-address /* As specified in the Logical LAN device tree node */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the Unit Address else H_Parameter</para>
</listitem>
<listitem>
<para>Interlock/carefully manipulate tables so that H_SEND_LOGICAL_LAN
performs safely.</para>
</listitem>
<listitem>
<para>Clear the associated page buffer list, prevent further
consumption of receive buffers and generation of receive
interrupts.</para>
</listitem>
<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
<para>H_FREE_LOGICAL_LAN is the only valid mechanism to reclaim the
memory pages registered via H_REGISTER_LOGICAL_LAN.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> If the hypervisor returns an
H_Busy, H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, software must
call H_FREE_LOGICAL_LAN again with the same parameters. Software may
choose to treat H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same
as H_Busy. The hypervisor, prior to returning H_Busy,
H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, will have placed the
virtual adapter in a state that will cause it to not accept any new work
nor surface any new virtual interrupts (no new frames will arrive,
etc.).</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_41506">
<title>H_ADD_LOGICAL_LAN_BUFFER</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware */
hcall ( const uint64 H_ADD_LOGICAL_LAN_BUFFER,/* Adds a receive buffer to the */
/* receive buffer pool */
uint64 unit-address, /* As specified in the Logical LAN device tree node */
uint64 buf /* Buffer descriptor of the receive buffer to add to the */
/* receive buffer pool */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>buf: Buffer Descriptor of new I/O buffer</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Checks that unit address is OK else H_Parameter.</para>
</listitem>
<listitem>
<para>Checks that I/O Address is within range of DMA window.</para>
</listitem>
<listitem>
<para>Scans the buffer list for a pool of buffers of the length
specified in the Descriptor</para>
</listitem>
<listitem>
<para>If one does not exist (and there is still room in the buffer
list, create a new pool entry else H_Resource).</para>
</listitem>
<listitem>
<para>Uses enqueue procedure that is compatible with H_SEND_LOGICAL_LAN
hcall()&#8217;s dequeue procedure</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> Since the buffer queue is based upon I/O
addresses that are checked by H_SEND_LOGICAL_LAN, it is only necessary to
insure that the enqueue/dequeue are internally consistent. If the owning
OS corrupts his buffer descriptors or buffer queue pointers, this is
caught by H_SEND_LOGICAL_LAN and/or the corruption is contained within
the OS&#8217;s partition.</para>
<para><emphasis role="bold">Architecture Note:</emphasis> Consideration was given to define the enqueue
algorithm and have the DD do the enqueue itself. However, no designs
presented themselves that eliminated the timing windows caused by adding
and removing pool lists without the introduction of OS/FW
interlocks.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_83832">
<title>H_FREE_LOGICAL_LAN_BUFFER</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware, H_Not_Found */
hcall ( const uint64 H_FREE_LOGICAL_LAN_BUFFER,/* Removes a buffer of the specified */
/* size, if available, from the receive buffer pool */
uint64 unit-address,/* As specified in the Logical LAN device tree node */
uint64 bufsize /* Size of the buffer to remove from the receive buffer pool */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
</listitem>
<listitem>
<para>bufsize: The size of the buffer that is being requested to be
removed from the receive buffer pool.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Check that unit address is valid, else return H_Parameter.</para>
</listitem>
<listitem>
<para>Scan the buffer list for a pool of buffers of the length
specified in bufsize, and return H_Not_Found if one does not
exist.</para>
</listitem>
<listitem>
<para>Place an entry on receive queue for buffer of specified size,
with Control field Bit 1 set to 0, and return H_Success</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_62760">
<title>H_SEND_LOGICAL_LAN</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Dropped, H_Hardware, H_Busy */
hcall ( const uint64 H_SEND_LOGICAL_LAN, /* Send a message on the logical LAN */
uint64 unit-address, /* As specified in the Logical LAN device tree node */
uint64 buff-1, /* The message content including source and destination MAC */
uint64 buff-2, /* addresses and optional IEEE VLAN header is contained in */
uint64 buff-3, /* 1 - 6 buffers each contiguous (in I/O space) buffer is */
uint64 buff-4, /* passed using a buffer descriptor. A buffer descriptor */
uint64 buff-5, /* with a control byte of “invalid” indicates the end of */
uint64 buff-6, /* the message (only the number of buffers needed are */
/* used). */
uint64 continue-token, /* value of 0 on first call, value returned in R4 on */
/* H_Busy */
uint64 mss /* The Maximum Segment Size to use when segmenting */
/* the message */
);]]></programlisting>
<para>The H_Dropped return code indicates to the sender that one or more
intended receivers did not receive the message.</para>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>buff-1: Buffer Descriptor #1</para>
</listitem>
<listitem>
<para>buff-2: Buffer Descriptor #2</para>
</listitem>
<listitem>
<para>buff-3: Buffer Descriptor #3</para>
</listitem>
<listitem>
<para>buff-4: Buffer Descriptor #4</para>
</listitem>
<listitem>
<para>buff-5: Buffer Descriptor #5</para>
</listitem>
<listitem>
<para>buff-6: Buffer Descriptor #6</para>
</listitem>
<listitem>
<para>continue-token: Used to continue a transfer if H_Busy is
returned. Set to 0 on the first call. If H_Busy is returned, then call
again but use the value returned in R4 from the previous call as the
value of continue-token.</para>
</listitem>
<listitem>
<para>mss: The Maximum Segment Size to use if segmenting of the message
is necessary.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>If continue-token is non-zero, then do appropriate checks to see
that parameters and buffers are still valid, and pickup where the
previous transfer left off for the specified unit address, based on the
value of the continue-token.</para>
</listitem>
<listitem>
<para>If continue-token is zero and if previous H_SEND_LOGICAL_LAN for
the specified unit address was suspended with H_Busy and never completed,
then cleanup the state from the previously suspended call before
proceeding.</para>
</listitem>
<listitem>
<para>If the caller has enabled large send/receive, verify the MSS is
0 or at least 16 – else H_Parameter.</para>
</listitem>
<listitem>
<para>Verifies the VLAN number -- else H_Parameter.</para>
</listitem>
<listitem>
<para>If the caller has enabled large send/receive and the MSS is not 0,
verify the message contains an Ethernet packet using IPv4 or IPv6 and
TCP – else H_Parameter. The complete TCP header must be within the
first 4096 bytes of the frame.</para>
</listitem>
<listitem>
<para>Proceeds down the 6 buffer descriptors until the first one that
has a length of 0</para>
<itemizedlist>
<listitem>
<para>If the
<emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis> property exist
in the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node of the device tree, then if the length
is greater than the value of this property, return H_Parameter</para>
</listitem>
<listitem>
<para>For the length of the buffer:</para>
<itemizedlist>
<listitem>
<para>Verifies the I/O buffer addresses translate through the
sender&#8217;s RTCE table else H_Parameter.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Verifies the destination MAC address for the VLAN</para>
<itemizedlist>
<listitem>
<para>If MAC address is not cached and there exists a Trunk Adapter for
the VLAN, then flags the message as destined for the Trunk Adapter and
continues processing</para>
</listitem>
<listitem>
<para>If MAC address is not cached and a Trunk Adapter does not exist
for the VLAN, then drop the message (H_Dropped)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For each Destination MAC Address (broadcast MAC address turns
into multi-cast to all destinations on the specified VLAN):</para>
<itemizedlist>
<listitem>
<para>In the case of multicast MAC addresses the following algorithm
defines the members of the receiver class for a given VLAN:</para>
<para>For each logical lan IOA that would be a target for a broadcast
from the source IOA:</para>
<itemizedlist>
<listitem>
<para>If the receiving IOA is not enabled for non-broadcast multicast
frames then continue</para>
</listitem>
<listitem>
<para>If the receiving IOA is not enabled for filtering non-broadcast
multicast frames then copy the frame to the IOA's receive buffer</para>
<para>Else</para>
<itemizedlist>
<listitem>
<para>If (lookup filter (table index)) then copy the frame to the
IOA's receive buffer</para>
</listitem>
<listitem>
<para>Else if the receiving IOA is not enabled for filtering
non-broadcast multicast frames then copy the frame to the IOA's receive
buffer /*allows for races on filter insertion */</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>int lookup filter (table index)</para>
<itemizedlist>
<listitem>
<para>Firmware implementation designed algorithm</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the MSS parameter is being used, the receiver IOA is not enabled for large receive, and the TCP payload in the frame is larger than the value of the mss parameter, the TCP payload of the message is divided into separate messages with copies of the MAC, VLAN, IP, and TCP headers in each.</para>
</listitem>
<listitem>
<para>For each message segment (packets without an MSS will be sent
as a single segment):</para>
<itemizedlist>
<listitem>
<para>Searches the receiver&#8217;s receive queue for a suitable buffer
and atomically dequeues it:</para>
<itemizedlist>
<listitem>
<para>If no suitable buffer is found, the receiver&#8217;s dropped
packet counter (last 8 bytes of buffer list) is incremented and
processing proceeds to the next receiver if any.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the receiver has enabled large-receive support, write
the MSS value in the second 8 bytes of the selected receive
buffer.</para>
</listitem>
<listitem>
<para>If segmentation is required, firmware will update portions
of the IP and TCP headers as necessary.
<itemizedlist>
<listitem>
<para>If the packet is using IPv4, firmware will always
regenerate the checksum for each segment.</para>
</listitem>
<listitem>
<para>For each segment, firmware will increment the IP
ident field by 1. It is the sender's responsibility
to ensure that no other packets are sent with the
colliding ident values.</para>
</listitem>
<listitem>
<para>If the receiver has not enabled checksum offload,
firmware will update the checksum in the TCP header.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Copy the send data in to the selected receive buffer, build a
receive queue entry, and generate an interrupt to the receiver if the
interrupt is enabled.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If any frames were dropped return H_Dropped else return
H_Success. This may happen if the receiver is low on buffers of the
correct size.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Firmware Implementation Note:</emphasis> If during the
processing of the H_SEND_LOGICAL_LAN call, it becomes necessary to
temporarily suspend the processing of the call (for example, due to the
length of time it is taking to process the call), the firmware may return
a continuation token in R4, along with the return code of H_Busy. The
value of the continuation token is up to the firmware, and will be passed
back by the software as the continue-token parameter on the next call of
H_SEND_LOGICAL_LAN.</para>
<para>This hcall() interlocks with H_MIGRATE_DMA to allow for migration
of TCE mapped DMA pages.</para>
<para><emphasis role="bold">Note:</emphasis> It is possible for either or both the sending
and receiving OS to modify its RTCE tables so as to affect the TCE
translations being actively used by H_SEND_LOGICAL_LAN. This is an error
condition on the part of the OS. Implementations need only insure that
such conditions do not corrupt memory in innocent partitions and should
not add path length to protect guilty partitions. By all means the path
length of H_GET_TCE and H_PUT_TCE should not be increased. If reasonably
possible, without significant path length addition, implementations
should: On send buffer translation corruption, return H_Parameter to the
sender and either totally drop the packet prior to reception, or if the
receive buffer has been processed past the point of transparent
recycling, mark the receive buffer as received in error in the receive
queue. On receive buffer translation corruption, terminate the data copy
to the receive buffer and mark the buffer as received in error in the
receive queue.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_71401">
<title>H_MULTICAST_CTRL</title>
<para>This hcall() controls the reception of non-broadcast multicast
packets (those with the high order address byte being odd but not the all
1&#8217;s address). All implementations support the enabling and
disabling of the reception of all multicast packets on their V-LAN.
Additionally, the l-lan device driver through this call may ask the
firmware to filter multicast packets for it. That is, receive packets
only if they contain multicast addresses specified by the device driver.
The number of simultaneous multicast packet filters supported is
implementation dependent, and is specified in the
<emphasis role="bold"><literal>&#8220;ibm,mac-address-filters&#8221;</literal></emphasis> property of the
l-lan device tree node. Therefore, the device driver must be prepared to
have any filter request fail, and fall back to enabling reception of all
multicast packets and filtering them in the device driver. Semantically,
the device driver may ask that the reception of multicast packets be
enabled or disabled, further if reception is enabled, they may be
filtered by only allowing reception of packets who&#8217;s mac address
matches one of the entries in the filter table. The call also manages the
contents of the mac address filter table. Individual mac addresses may be
added, or removed, and the filter table may be cleared. If the filter
table is modified by a call, there is the possibility that a packet may
be improperly filtered (one that was to be filtered out may get through
or one that should have gotten through may be dropped) this is done to
avoid adding extra locking to the packet processing code. In most cases
higher level protocols will handle the condition (since firmware
filtering is simply a performance optimization), if, however, a specific
condition requires complete accuracy, the device driver can disable
filtering prior to an update, do its own filtering (as would be required
if the number of receivers exceeded the number of filters in the filter
table) update the filter table, and then reenable filtering.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more parameters were invalid */
/* H_Constrained: The operation failed because of resource */
/* constraints (too many filter requests */
/* H_Not_Found: The requested remove object was not found */
/* H_Hardware: The operation failed because of a hardware */
/* error */
hcall ( const uint64 H_MULTICAST_CTRL, /* Controls multicast address filtering. */
uint64 unit-address, /*As specified in the Logical LAN device tree node */
uint64 flags, /* Two sets of encoded flag fields control the function */
/* -- Bits 44-47 control the multicast enables */
/* Bit 44 = 0 do not modify enable reception of */
/* multicast frames value of bit 46 ignored */
/* Bit 44 = 1 modify enable reception of multicast */
/* frames
/* if bit 46 = 1 allow reception of multicast */
/* frames */
/* if bit 46 = 0 prohibit reception of all */
/* multicast frames */
/* Bit 45 = 0 do not modify filtering of multicast */
/* frames value of bit 47 ignored */
/* Bit 45 = 1 modify enable of filtering of multicast */
/* frames */
/* if bit 47 = 1 if reception of multicast */
/* frames are allowed, further filter frames */
/* via mac address filter table */
/* if bit 47 = 0 if reception of multicast */
/* frames are allowed, do not filter out any */
/* due to mac address filter table */
/* -- Bits 62 and 63 control modification of the mac address */
/* filter table */
/* -- Bits 62 and 63 sub decode: */
/* 00 Leave filter table unmodified */
/* 01 Add specified MAC filter address to the table */
/* 10 Remove specified MAC filter address from the */
/* table */
/* 11 Clear the MAC filter address table */
/* All other flag bits are reserved */
uint64 multicast-address /* 8 byte MAC multicast address to be enabled (11) */
/* or disabled (10) */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>flags: Only bits 44-47 and 62-63 are defined all other bits
should be zero.</para>
</listitem>
<listitem>
<para>multi-cast-address: Multicast MAC address, if flag bits 62 and 63
are 01 or 10, else this parameter is ignored.</para>
</listitem>
</itemizedlist>
<para>Return value in register R4:</para>
<para>State of Enables and Count of MAC Filters in table.</para>
<para>Format:</para>
<programlisting><![CDATA[Bits: 0--------------------------------------------45,46-47,48--------------63
Reserved R F MAC Filter Count]]></programlisting>
<para>R = The value of the Receipt Enable bit</para>
<para>F = The value of the Filter Enable bit</para>
<para>MAC Filter Count -- 16 bit count of the number of MAC Filters in
the multicast filter table.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate the unit-address parameter else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Validate that no reserved flag bit = 1 else return
H_Parameter.</para>
</listitem>
<listitem>
<para>If any bits are on in the high order two bytes of the MAC
parameter Return H_Parameter</para>
</listitem>
<listitem>
<para>Modify Enables per specification if requested.</para>
</listitem>
<listitem>
<para>Modify the Filter Table per specification if requested filtering
is disable during any filter table modification and filter enable state
restored after filter table modification).</para>
<itemizedlist>
<listitem>
<para>If don't modify RC=H_Success</para>
</listitem>
<listitem>
<para>If Clear all: initialize the filter table, RC=H_Success</para>
</listitem>
<listitem>
<para>If Add:</para>
<itemizedlist>
<listitem>
<para>If there is room in the table insert new MAC Filter entry, MAC
Filter count++, RC=H_Success</para>
</listitem>
<listitem>
<para>Else RC=H_Constrained</para>
</listitem>
<listitem>
<para>(duplicates are silently dropped -- filter count stays the same
RC=H_Success)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If Remove:</para>
<itemizedlist>
<listitem>
<para>Locate the specified entry in the MAC Filter Table</para>
</listitem>
<listitem>
<para>If Found remove the entry, MAC Filter count--,
RC=H_Success</para>
</listitem>
<listitem>
<para>Else RC=H_Not_Found</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Load the Enable Bits into R4 bits 46 and 47 Load the MAC Filter
count into R4 Bits 48-63</para>
</listitem>
<listitem>
<para>Return RC</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_19596">
<title>H_CHANGE_LOGICAL_LAN_MAC</title>
<para>This hcall() allows the changing of the virtual IOA&#8217;s MAC
address.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success, H_Parameter, H_Hardware */
hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */
uint64 unit-address, /* As specified in the Logical LAN device tree node */
uint64 mac-address /* New MAC address for the virtual IOA). */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property</para>
</listitem>
<listitem>
<para>mac-address: The new receive filter MAC address</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validates the unit address, else H_Parameter</para>
</listitem>
<listitem>
<para>Records the low order 6 bytes of mac-address for filtering future
incoming messages</para>
</listitem>
<listitem>
<para>Returns H_Success</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_67792">
<title>H_ILLAN_ATTRIBUTES</title>
<para>There are certain ILLAN attributes that are made visible to and can
be manipulated by partition software. The H_ILLAN_ATTRIBUTES hcall is
used to read and modify the attributes (see
<xref linkend="dbdoclet.50569350_67792" />).
<xref linkend="dbdoclet.50569350_11661" /> defines the attributes that are
visible and manipulatable.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569350_11661">
<title>ILLAN Attributes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Bit(s)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0-45</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>46</para>
</entry>
<entry>
<para>Checksum Offload Non-zero Checksum Field Support</para>
</entry>
<entry>
<para>This bit is implemented when PHYP supports sending TCP
packets with a non-zero TCP checksum field when bit 6 of the
buffer descriptor (the "No Checksum" bit) is set. This bit
indicates
<xref linkend="req_illan_attributes_checksum_offload_3" xrefstyle="select: labelnumber nopage" />
is not required.</para>
</entry>
</row>
<row>
<entry>
<para>47</para>
</entry>
<entry>
<para>Large send/receive enabled</para>
</entry>
<entry>
<para>This bit is implemented for a VIOA whenever the Large Send option is
implemented for TCP. This bit is initially set to 0 by the firmware and
the ILLAN DD may attempt to set it to 1 by use of the H_ILLAN_ATTRIBUTES
hcall() if the DD supports the option to receive TCP packets sent using
H_SEND_LOGICAL_LAN with a non-zero MSS. Firmware will not allow changing
the state of this bit if it does not support Large Send as indicated by
bit 48 for the VIOA (H_Constrained would be returned in this case from
the H_ILLAN_ATTRIBUTES hcall() when this bit is a 1 in the set-mask).
The state of this bit cannot be changed between the time that the ILLAN is
registered by an H_REGISTER_LOGICAL_LAN and it is de-registered by
an H_FREE_LOGICAL_LAN. See
<xref linkend="sec_illan_large_send_indication" />
for more information.<?linebreak?>
1: The partition software has indicated that it supports receiving
large-send packets sent using H_SEND_LOGICAL_LAN with a non-zero MSS.
If no buffers are available to fit the large packet, it will be
dropped.<?linebreak?>
0: The partition software has not indicated that it supports the
Large Receive option for packets sent using H_SEND_LOGICAL_LAN,
or it has but the firmware does not support the option, or supports
the option but not for this protocol or for this VIOA.</para>
</entry>
</row>
<row>
<entry>
<para>48</para>
</entry>
<entry>
<para>Large Send Indication Supported</para>
</entry>
<entry>
<para>The bit is implemented when firmware supports the large send
indication bit in the I/O descriptor passed to H_SEND_LOGICAL_LAN.
This bit allows the partition software to enable large receive as
described in
<xref linkend="sec_illan_large_send_indication" />.<?linebreak?>
0: Software must not request large send indication,
by setting Bit 5 of the buffer descriptor.<?linebreak?>
1: Software may request large send indication, by
setting Bit 5 of the buffer descriptorand may supply an MSS value
greater than 0.</para>
</entry>
</row>
<row>
<entry>
<para>49</para>
</entry>
<entry>
<para>Port Disabled</para>
</entry>
<entry>
<para>When the bit is a 1, the port is disabled. When
the port is disabled, no Ethernet traffic will be
permitted to be transmitted or received.
H_Parameter will be returned if this bit is turned
on in either the reset or set masks. On firmware
that does not support this function, bit 49 is
reserved and required to be 0. OS can infer that
means the port is enabled.</para>
</entry>
</row>
<row>
<entry>
<para>50</para>
</entry>
<entry>
<para>Checksum Offload Padded Packet Support</para>
</entry>
<entry>
<para>This bit is implemented when the ILLAN Checksum Offload
Padded Packet Support option is implemented. See
<xref linkend="dbdoclet.50569350_39278" />.</para>
<para>0: Software must not request checksum offload, by setting
Bit 6 of the buffer descriptor (the No Checksum bit), for
packets that have been padded.</para>
<para>1: Software may request checksum offload, by setting Bit
6 of the buffer descriptor (the No Checksum bit), for packets
that have been padded.</para>
</entry>
</row>
<row>
<entry>
<para>51</para>
</entry>
<entry>
<para>Buffer Size Control</para>
</entry>
<entry>
<para>This bit is implemented when the ILLAN Buffer Size
Control option is implemented. This bit allows the partition
software to inhibit the use of too large of a buffer for
incoming packets, when a reasonable size buffer is not
available. The state of this bit cannot be changed between the
time that the ILLAN is registered by an H_REGISTER_LOGICAL_LAN
and it is deregistered by an H_FREE_LOGICAL_LAN. See also
<xref linkend="dbdoclet.50569350_39077" />.</para>
<para>1: The hypervisor will keep a history of what buffer
sizes have been registered. When a packets arrives the history
is searched to find the smallest buffers size that will contain
the packet. If that buffer size is depleted then the packet is
dropped by the hypervisor (H_Dropped) instead of searching for
the next larger available buffer.</para>
<para>0: This is the initial value. When a packet arrives, the
available buffers are searched for the smallest available
buffer that will hold the packet, and the packet is not dropped
unless no buffer is available in which the packet will
fit.</para>
</entry>
</row>
<row>
<entry>
<para>52-55</para>
</entry>
<entry>
<para>Trunk Adapter Priority</para>
</entry>
<entry>
<para>This field is implemented for a VIOA whenever the ILLAN
Backup Trunk Adapter option is implemented and the VIOA is a
Trunk Adapter (the Active Trunk Adapter bit will be
implemented, also, in this case). If this field is a 0, then
the either the ILLAN Backup Trunk Adapter option is not
implemented or it is implemented but this VIOA is not a Trunk
Adapter. A non-0 value in this field reflects the priority of
the node in the backup Trunk Adapter hierarchy, with a value of
1 being the highest (most favored) priority, the value of 2
being the next highest priority, and so on. This field may or
may not be changeable by the partition firmware via the
H_ILLAN_ATTRIBUTES hcall() (platform implementation dependent).
If not changeable, then attempts to change this field will
result in a return code of H_Constrained. See also
<xref linkend="dbdoclet.50569350_17923" />.</para>
</entry>
</row>
<row>
<entry>
<para>56-60</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>61</para>
</entry>
<entry>
<para>TCP Checksum Offload Support for IPv6</para>
</entry>
<entry>
<para>This bit is implemented for a VIOA whenever the ILLAN
Checksum Offload Support option is implemented for TCP, the
IPv6 protocol, and the following extension headers:</para>
<para>Hop-by-Hop Options</para>
<para>Routing</para>
<para>Destination Options</para>
<para>Authentication</para>
<para>Mobility</para>
<para>This bit is initially set to 0 by the firmware and the
ILLAN DD may attempt to set it to a 1 by use of the
H_ILLAN_ATTRIBUTES hcall() if the DD supports the option for
TCP and IPv6. Firmware will not allow changing the state of
this bit if it does not support Checksum Offload Support for
TCP for IPv6 for the VIOA (H_Constrained would be returned in
this case from the H_ILLAN_ATTRIBUTES hcall() when this bit is
a 1 in the set-mask). This state of this bit cannot be changed
between the time that the ILLAN is registered by an
H_REGISTER_LOGICAL_LAN and it is deregistered by an
H_FREE_LOGICAL_LAN. See
<xref linkend="dbdoclet.50569350_53238" /> for more
information.<?linebreak?>
1: The partition software has indicated that it supports
the ILLAN Checksum Offload Support option for TCP and IPv6
protocol and for the above stated extension headers by using
the H_ILLAN_ATTRIBUTES hcall() with this bit set to a 1 in the
set-mask, and the firmware has verified that it supports this
protocol for the option for the VIOA.<?linebreak?>
0: The partition software has not indicated that it
supports the ILLAN Checksum Offload Support option for TCP and
IPv6 protocol and for the above stated extension headers by
using the H_ILLAN_ATTRIBUTES hcall() with this bit set to a 1
in the set-mask, or it has but the firmware does not support
the option, or supports the option but not for this protocol or
for this VIOA.</para>
</entry>
</row>
<row>
<entry>
<para>62</para>
</entry>
<entry>
<para>TCP Checksum Offload Support for IPv4</para>
</entry>
<entry>
<para>This bit is implemented for a VIOA whenever the ILLAN
Checksum Offload Support option is implemented for TCP and the
IPv4 protocol. This bit is initially set to 0 by the firmware
and the ILLAN DD may attempt to set it to a 1 by use of the
H_ILLAN_ATTRIBUTES hcall() if the DD supports the option for
TCP and IPv4. Firmware will not allow changing the state of
this bit if it does not support Checksum Offload Support for
TCP or IPv4 for the VIOA (H_Constrained would be returned in
this case from the H_ILLAN_ATTRIBUTES hcall() when this bit is
a 1 in the set-mask). This state of this bit cannot be changed
between the time that the ILLAN is registered by an
H_REGISTER_LOGICAL_LAN and it is deregistered by an
H_FREE_LOGICAL_LAN. See
<xref linkend="dbdoclet.50569350_53238" /> for more
information.</para>
<para>1: The partition software has indicated that it supports
the ILLAN Checksum Offload Support option for TCP and IPv4
protocol by using the H_ILLAN_ATTRIBUTES hcall() with this bit
set to a 1 in the set-mask, and the firmware has verified that
it supports this protocol for the option for the VIOA.</para>
<para>0: The partition software has not indicated that it
supports the ILLAN Checksum Offload Support option for TCP and
IPv4 by using the H_ILLAN_ATTRIBUTES hcall() with this bit set
to a 1 in the set-mask, or it has but the firmware does not
support the option, or supports the option but not for this
protocol or for this VIOA.</para>
</entry>
</row>
<row>
<entry>
<para>63</para>
</entry>
<entry>
<para>Active Trunk Adapter</para>
</entry>
<entry>
<para>This bit is implemented for a VIOA whenever the ILLAN
Backup Trunk Adapter option is implemented and the VIOA is a
Trunk Adapter (the Trunk Adapter Priority field will be
implemented, also, in this case).</para>
<para>This bit is initially set to 0 by the firmware for an
inactive Trunk Adapter.</para>
<para>This bit is initially set to 1 by the firmware for an
active Trunk Adapter.</para>
<para>This bit will be changed from a 0 to a 1 when all the
following a true: (1) the partition software (via the
H_ILLAN_ATTRIBUTES hcall() with this bit set to a 1 in the
set-mask) attempts to set this bit to a 1, (2) the firmware
supports the Backup Trunk Adapter option, (3) the VIOA is a
Trunk Adapter.</para>
<para>This bit will be changed from a 1 to a 0 by the firmware
when another Trunk Adapter has had its Active Trunk Adapter bit
changed from a 0 to a 1.</para>
<para>See
<xref linkend="dbdoclet.50569350_17923" /> for more
information.</para>
<para>1: The VIOA is the active Trunk Adapter.</para>
<para>0: The VIOA is not an active Trunk Adapter or is not a
Trunk Adapter at all.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_67792"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>If the H_ILLAN_ATTRIBUTES hcall is
implemented, then it must implement the attributes as they are defined in
<xref linkend="dbdoclet.50569350_11661" /> and the syntax and semantics as
defined in
<xref linkend="dbdoclet.50569350_67792" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_67792"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The H_ILLAN_ATTRIBUTES hcall must ignore
bits in the set-mask and reset-mask which are not implemented for the
specified unit-address and must process as an exception those which
cannot be changed for the specified unit-address (H_Constrained
returned), and must return the following for the ILLAN Attributes in
R4:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>A value of 0 for unimplemented bit positions.</para>
</listitem>
<listitem>
<para>The resultant field values for implemented fields.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more parameters were in error */
/* H_Constrained: One or more parameters was not changeable */
/* to the value requested the result was constrained to a */
/* legitimate value for the implementation */
/* H_Hardware Operation: failed because of hardware error */
hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
/* Attributes*/
uint64 unit-address, /* The ILLAN Unit Address on which to perform this */
/* operation */
uint64 reset-mask, /* Mask of Attribute bits to be reset */
uint64 set-mask /* Mask of Attribute bits to be set */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<para>unit-address: Unit Address per device tree node
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property. The ILLAN unit address on
which this Attribute modification is to be performed.</para>
<para>reset-mask: The bit-significant mask of bits to be reset in the
ILLAN&#8217;s Attributes (the reset-mask bit definition aligns with the
bit definition of the ILLAN&#8217;s Attributes, as defined in
<xref linkend="dbdoclet.50569350_11661" />). The complement of the
reset-mask is ANDed with the ILLAN&#8217;s Attributes, prior to applying
the set-mask. See semantics for more details on any field-specific
actions needed during the reset operations. If a particular field
position in the ILLAN Attributes is not implemented, then the
corresponding bit(s) in the reset-mask are ignored.</para>
<para>set-mask: The bit-significant mask of bits to be set in the
ILLAN&#8217;s Attributes (the set-mask bit definition aligns with the bit
definition of the ILLAN&#8217;s Attributes, as defined in
<xref linkend="dbdoclet.50569350_11661" />). The set-mask is ORed with
the ILLAN&#8217;s Attributes, after to applying the reset-mask. See
semantics for more details on any field-specific actions needed during
the set operations. If a particular field position in the ILLAN
Attributes is not implemented, then the corresponding bit(s) in the
set-mask are ignored.</para>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that Unit Address belongs to the partition, else
H_Parameter.</para>
</listitem>
<listitem>
<para>Reset/set the bits in the ILLAN Attributes, as indicated by the
rest-mask and set-mask except as indicated in the following
conditions.</para>
</listitem>
<listitem>
<para>If the Buffer Size Control bit is trying to be changed from a 0
to a 1 and any of the following is true, then do not allow the change
(H_Constrained will be returned):</para>
<itemizedlist>
<listitem>
<para>The ILLAN is active. That is, the ILLAN has been registered
(H_REGISTER_LOGICAL_LAN) but has not be deregistered
(H_FREE_LOGICAL_LAN).</para>
</listitem>
<listitem>
<para>The firmware does not support the ILLAN Buffer Size Control
option.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the Buffer Size Control bit is trying to be changed from a 1
to a 0 and any of the following is true, then do not allow the change
(H_Constrained will be returned):</para>
<itemizedlist>
<listitem>
<para>The ILLAN is active. That is, the ILLAN has been registered
(H_REGISTER_LOGICAL_LAN) but has not be deregistered
(H_FREE_LOGICAL_LAN).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If either the TCP Checksum Offload Support for IPv4 bit or TCP
Checksum Offload Support for IPv6 bit is trying to be changed from a 0 to
a 1 and any of the following is true, then do not allow the change
(H_Constrained will be returned):</para>
<itemizedlist>
<listitem>
<para>The ILLAN is active. That is, the ILLAN has been registered
(H_REGISTER_LOGICAL_LAN) but has not be deregistered
(H_FREE_LOGICAL_LAN).</para>
</listitem>
<listitem>
<para>The firmware does not support the ILLAN Checksum Offload Support
option or supports it, but not for the specified protocol(s) or does not
support it for this VIOA.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the TCP Checksum Offload Support for IPv4 bit or TCP Checksum
Offload Support for IPv6 bit is trying to be changed from a 1 to a 0 and
any of the following is true, then do not allow the change (H_Constrained
will be returned):</para>
<itemizedlist>
<listitem>
<para>The ILLAN is active. That is, the ILLAN has been registered
(H_REGISTER_LOGICAL_LAN) but has not be deregistered
(H_FREE_LOGICAL_LAN).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the Active Trunk Adapter bit is trying to be changed from a 0
to a 1 and any of the following is true, then do not allow the change
(H_Constrained will be returned):</para>
<itemizedlist>
<listitem>
<para>The firmware does not support the ILLAN Backup Trunk Adapter
option or this VIOA is not a Trunk Adapter.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If the Active Trunk Adapter bit is trying to be changed from a 1
to a 0, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If the Active Trunk Adapter bit is changed from a 0 to a 1 for a
VIOA, then also set any previously active Trunk Adapter&#8217;s Active
Trunk Adapter bit from a 1 to a 0.</para>
</listitem>
<listitem>
<para>If the Trunk Adapter Priority field is trying to be changed from
0 to a non-0 value, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If the Trunk Adapter Priority field is trying to be changed from
a non-0 value to another non-0 value and either the parameter is not
changeable or the change is not within the platform allowed limits, then
do not allow the change (H_Constrained will be returned).</para>
</listitem>
<listitem>
<para>Load R4 with the value of the ILLAN&#8217;s Attributes, with any
unimplemented bits set to 0, and if all requested changes were made then
return H_Success, otherwise return H_Constrained.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569350_53237">
<title>Other hcall()s extended or used by the Logical LAN
Option</title>
<para />
<section>
<title>H_VIO_SIGNAL</title>
<para>The H_VIO_SIGNAL hcall() is used by multiple VIO options.</para>
</section>
<section xml:id="dbdoclet.50569350_12056">
<title>H_EOI</title>
<para>The H_EOI hcall(), when specifying an interrupt source number
associated with an interpartion logical LAN IOA, incorporates the
interrupt reset function.</para>
</section>
<section xml:id="dbdoclet.50569350_16027">
<title>H_XIRR</title>
<para>This call is extended to report the virtual interrupt source number
associated with virtual interrupts associated with an ILLAN IOA.</para>
</section>
<section xml:id="dbdoclet.50569350_37611">
<title>H_PUT_TCE</title>
<para>This standard hcall() is used to manage the ILLAN IOA&#8217;s I/O
translations.</para>
</section>
<section xml:id="dbdoclet.50569350_18045">
<title>H_GET_TCE</title>
<para>This standard hcall() is used to manage the ILLAN IOA&#8217;s I/O
translations.</para>
</section>
<section xml:id="dbdoclet.50569350_96098">
<title>H_MIGRATE_DMA</title>
<para>This hcall() is extended to serialize with the H_SEND_LOGICAL_LAN
hcall() to allow for migration of TCE mapped DMA pages.</para>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569350_22936">
<title>RTAS Calls Extended or Used by the Logical LAN
Option</title>
<para>Platforms may combine the Logical LAN option with most other LoPAR
options such as dynamic reconfiguration by including the appropriate OF
properties and extending the associated firmware calls. However, the
<emphasis>ibm,set-xive, ibm,get-xive, ibm,int-off,</emphasis>
and
<emphasis>ibm,int-on</emphasis> RTAS calls are extended as part of the
base support.</para>
</section>
<section xml:id="sec_illan_req">
<title>Interpartition Logical LAN Requirements</title>
<para>The following requirements are mandated for platforms implementing
the ILLAN option.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret
logical LAN buffer descriptors as defined in
<xref linkend="dbdoclet.50569350_35439" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject
logical LAN buffer descriptors that are not 8 byte aligned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret the
first byte of a logical LAN buffer descriptor as a control byte, the high
order bit being the valid bit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must set the next
to high order bit of the control byte of the logical LAN buffer
descriptor for the receive queue to the inverse of the value currently
being used to indicate a valid receive queue entry.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret the
2nd through 4th bytes of a logical LAN buffer descriptor as the binary
length of the buffer in I/O space (relative to the TCE mapping table
defined by the logical IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret the
5th through 8th bytes of a logical LAN buffer descriptor as the binary
beginning address of the buffer in I/O space (relative to the TCE mapping
table defined by the logical IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret
logical LAN Buffer Lists as defined in
<xref linkend="dbdoclet.50569350_48856" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject
logical LAN Buffer Lists that are not mapped relative to the TCE mapping
table defined by the logical IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject
logical LAN buffer lists that are not 4 KB aligned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret the
first 8 bytes of a logical LAN buffer list as a buffer descriptor for the
logical IOA&#8217;s Receive Queue.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret the
logical LAN receive queue as defined in
<xref linkend="dbdoclet.50569350_59321" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive queue that is not mapped relative to the TCE mapping
table defined by the logical IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive queue that is not aligned on a 4 byte
boundary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive queue that is not an exact multiple of 12 bytes
long.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must manage the
logical LAN receive queue as a circular buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must enqueue 12
byte logical LAN receive queue entries when a new message is
received.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569350_45644">
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis>
The platform must
set the last 8 bytes of the logical LAN receive queue entry to the value
of the user supplied correlator found in the first 8 bytes of the logical
LAN receive buffer used to contain the message before setting the first 4
bytes of the logical LAN receive queue entry.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569350_57028">
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis>
The platform must
set the first 4 bytes of the logical LAN receive queue entry such that
the first byte contains the control field (high order bit the inverse of
the valid toggle in the receive queue buffer descriptor, next bit to a
one if the message payload is valid) and the last 3 bytes contains the
receive message length, after setting the correlator field in the last 8
bytes per Requirement
<xref linkend="dbdoclet.50569350_45644" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must when crossing
from the end of the logical LAN receive queue back to the beginning
invert the value of the valid toggle in the receive queue buffer
descriptor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform&#8217;s OF must
disable interrupts from the logical LAN IOA before initially passing
control to the booted client program.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-21.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must present (as
appropriate per RTAS control of the interrupt source number) the
partition owning a logical LAN receive queue the appearance of an
interrupt, from the interrupt source number associated, through the OF
device tree node, with the virtual device, when a new entry is enqueued
to the logical LAN receive queue and the last interrupt mode set via the
H_VIO_SIGNAL was &#8220;Enabled&#8221;, unless a previous interrupt from
the interrupt source number is still outstanding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-22.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must NOT present
the partition owning a logical LAN receive queue the appearance of an
interrupt, from the interrupt source number associated, through the OF
device tree node, with the virtual device, if the last interrupt mode set
via the H_VIO_SIGNAL was &#8220;Disabled&#8221;, unless a previous
interrupt from the interrupt source number is still outstanding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-23.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must interpret
logical LAN receive buffers as defined in
<xref linkend="dbdoclet.50569350_45114" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-24.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive buffer that is not mapped relative to the TCE mapping
table defined by the logical IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-25.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive buffer that is not aligned on a 4 byte
boundary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-26.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must reject a
logical LAN receive buffer that is not a minimum of 16 bytes long.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-27.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must not modify
the first 8 bytes of a logical LAN receive buffer, this area is reserved
for a user supplied correlator value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-28.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must not allow
corruption caused by a user modifying the logical LAN receive buffer from
escaping the user partition (except as a side effect of some another user
partition I/O operation).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-29.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>l-lan</literal></emphasis> OF device tree node must contain properties as
defined in
<xref linkend="dbdoclet.50569350_41555" />. (Other standard I/O adapter
properties are permissible as appropriate.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-30.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_REGISTER_LOGICAL_LAN hcall() as defined in
<xref linkend="dbdoclet.50569350_38939" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-31.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_FREE_LOGICAL_LAN hcall() as defined in
<xref linkend="dbdoclet.50569350_78305" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-32.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_ADD_LOGICAL_LAN_BUFFER hcall() as defined in
<xref linkend="dbdoclet.50569350_41506" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-33.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_SEND_LOGICAL_LAN hcall() as defined in
<xref linkend="dbdoclet.50569350_62760" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-34.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_SEND_LOGICAL_LAN hcall() such that an OS requested modification to an
active RTCE table entry cannot corrupt memory in other partitions.
(Except indirectly as a result of some other of the partition&#8217;s I/O
operations.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-35.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_CHANGE_LOGICAL_LAN_MAC hcall() as defined in
<xref linkend="dbdoclet.50569350_19596" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-36.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_VIO_SIGNAL hcall() as defined in
<xref linkend="dbdoclet.50569348_27549" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-37.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
extensions to the H_EOI hcall() as defined in
<xref linkend="dbdoclet.50569350_12056" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-38.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
extensions to the H_XIRR hcall() as defined in
<xref linkend="dbdoclet.50569350_16027" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-39.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_PUT_TCE hcall().</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-40.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
H_GET_TCE hcall().</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-41.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platform must implement the
extensions to the H_MIGRATE_DMA hcall() as defined in
<xref linkend="dbdoclet.50569350_96098" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_req"
xrefstyle="select: labelnumber nopage"/>-42.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN option:</emphasis> The platforms must emulate the
standard PowerPC External Interrupt Architecture for the interrupt source
numbers associated with the virtual devices via the standard RTAS and
hypervisor interrupt calls.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569350_89321">
<title>Logical LAN Options</title>
<para>The ILLAN option has several sub-options. The hypervisor reports to
the partition software when it supports one or more of these options, and
potentially other information about those option implementations, via the
implementation of the appropriate bits in the ILLAN Attributes, which can
be ascertained by the H_ILLAN_ATTRIBUTES hcall(). The same hcall() may be
used by the partition software to communicate back to the firmware the
level of support for those options where the firmware needs to know the
level of partition software support. The
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> property will exist
in the VIOA&#8217;s Device Tree node, indicating that the
H_ILLAN_ATTRIBUTES hcall() is implemented, and therefore that one or more
of the options are implemented. The following sections give more
details.</para>
<section xml:id="dbdoclet.50569350_17923">
<title>ILLAN Backup Trunk Adapter Option</title>
<para>The ILLAN Backup Trunk Adapter option allows the platform to
provide one or more backups to a Trunk Adapter, for reliability purposes.
Implementation of the ILLAN Backup Trunk Adapter option is specified to
the partition by the existence of the
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> property in the
VIOA&#8217;s Device Tree node and a non-0 value in the ILLAN Attributes
Backup Trunk adapter Priority field. A Trunk Adapter becomes the active
Trunk Adapter by calling H_ILLAN_ATTRIBUTES hcall() and setting its
Active Trunk Adapter bit. Only one Trunk Adapter is active for a VLAN at
a time. The protocols which determine which Trunk Adapter is active at
any particular time, is beyond the scope of this architecture.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_89321"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Backup Trunk Adapter option:</emphasis> The
platform must implement the ILLAN option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_89321"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Backup Trunk Adapter option:</emphasis> The
platform must implement the H_ILLAN_ATTRIBUTES hcall().</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_89321"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Backup Trunk Adapter option:</emphasis> The
platform must implement the
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis> properties in all the
Trunk Adapter nodes of the Device Tree.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_89321"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Backup Trunk Adapter option:</emphasis> The
platform must implement the Active Trunk Adapter bit and the Backup Trunk
Adapter Priority field in the ILLAN Attributes, as defined in
<xref linkend="dbdoclet.50569350_11661" />, for all Trunk Adapter
VIOAs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_89321"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Backup Trunk Adapter option:</emphasis> The
platform must allow only one Trunk Adapter to be active for a VLAN at any
given time, and must:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Make the determination of which one is active by whichever was
the most recent one to set its Active Trunk Adapter bit in their ILLAN
Attributes.</para>
</listitem>
<listitem>
<para>Turn off the Active Trunk Adapter bit in the ILLAN Attributes
for a Trunk Adapter when it is removed from the active Trunk Adapter
state.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569350_53238">
<title>ILLAN Checksum Offload Support Option</title>
<para>This option allows for the support of IOAs that do checksum offload
processing. This option allows for support at one end (client or server)
but not the other, on a per-protocol basis, with the hypervisor
generating the checksum when the client supports offload but the server
does not, and the operation is a send from the client.</para>
<section xml:id="sec_illan_gen">
<title>General</title>
<para>The H_ILLAN_ATTRIUBTES hcall is used to establish the common set of
checksum offload protocols to be supported between the firmware and the
partition software. The firmware indicates support for H_ILLAN_ATTRIBUTES
via the
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> property in the
VIOA&#8217;s Device Tree node. The partition software can determine which
of the Checksum Offload protocols (if any) that the firmware supports by
either attempting to set the bits in the ILLAN Attributes of the
protocols that the partition software supports or by calling the hcall()
with reset-mask and set-mask parameters of all-0&#8217;s (the latter
being just a query and not a request to support anything between the
partition and the firmware).</para>
<para>Two bits in the control field of the first buffer descriptor
specify which operations do not contain a checksum and which have had
their checksum already verified. See
<xref linkend="dbdoclet.50569350_35439" />. These two bits get
transferred to the corresponding control field of the Receive Queue
Entry, with the exception that the H_SEND_LOGICAL_LAN hcall will
sometimes set these to 0b00 (see
<xref linkend="dbdoclet.50569350_37925" />).</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_gen"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Checksum Offload Support option:</emphasis> The
platform must do all the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Implement the ILLAN option.</para>
</listitem>
<listitem>
<para>Implement the H_ILLAN_ATTRIBUTES hcall().</para>
</listitem>
<listitem>
<para>Implement the
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> property in the
VIOA&#8217;s Device Tree node.</para>
</listitem>
<listitem>
<para>Implement the appropriate Checksum Offload Support bit(s) of the
ILLAN Attributes, as defined in
<xref linkend="dbdoclet.50569350_11661" />.</para>
</listitem>
</orderedlist>
<para><emphasis role="bold">Software Implementation Note:</emphasis> Fragmentation and
encryption are not supported when the No Checksum bit of the Buffer
Descriptor is set to a 1.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569350_37925">
<title>H_SEND_LOGICAL_LAN Semantic Changes</title>
<para>There are several H_SEND_LOGICAL_LAN semantic changes required for
the ILLAN Checksum Offload Support option. See
<xref linkend="dbdoclet.50569350_62760" /> for the base semantics.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_37925"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Checksum Offload Support option:</emphasis> The
H_SEND_LOGICAL_LAN semantics must be changed as follows:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>As shown in
<xref linkend="dbdoclet.50569350_89622" />, and for multi-cast
operations, the determination in this table must be applied for each
destination.</para>
</listitem>
<listitem>
<para>If the No Checksum bit is set to a 1 in the first buffer
descriptor and the adapter is not a Trunk Adapter, and the source MAC
address does not match the adapter's MAC address, then drop the
packet.</para>
</listitem>
</orderedlist>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569350_89622">
<title>Summary of H_SEND_LOGICAL_LAN Semantics with Checksum
Offload</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="15*" align="center" />
<colspec colname="c5" colwidth="20*" />
<colspec colname="c6" colwidth="20*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Has Sender Set the Appropriate Checksum
Offload Support bit in the ILLAN Attributes for the Protocol
Being Used?</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Has Receiver Set the Appropriate
Checksum Offload Support bit in the ILLAN Attributes for the
Protocol Being Used?</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">No Checksum bit in the Buffer
Descriptor</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Checksum Good bit in the Buffer
Descriptor</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">H_SEND_LOGICAL_LAN Additional
Semantics</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Receiver DD Additional
Requirements</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>no</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>None.</para>
</entry>
<entry>
<para>None.</para>
</entry>
</row>
<row>
<entry>
<para>no</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry nameend="c4" namest="c3">
<para>Either bit non-0</para>
</entry>
<entry>
<para>Return H_Parameter</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>None.</para>
</entry>
<entry>
<para>None.</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Set the No Checksum and Checksum Good bits in the Buffer
Descriptor to 00 on transfer.</para>
</entry>
<entry>
<para>None.</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Generate checksum and set the No Checksum and Checksum
Good bits in the Buffer Descriptor to 00 on transfer.</para>
</entry>
<entry>
<para>None.</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>None.</para>
</entry>
<entry>
<para>Do not need to do checksum checking.</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>None.</para>
</entry>
<entry>
<para>Do not need to do checksum checking. Generate checksum if
packet is to be passed on to an external LAN (may be done by
the IOA or by the DD).</para>
</entry>
</row>
<row>
<entry>
<para>-</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Return H_Parameter</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>yes</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry nameend="c4" namest="c3">
<para>01 or 11 and packet type not supported by the hypervisor,
as indicated by the value returned by the H_ILLAN_ATTRIBUTES
hcall()</para>
</entry>
<entry>
<para>Return H_Parameter</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_37925"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Checksum Offload Support option:</emphasis> The
Receiver DD Additional Requirements shown in
<xref linkend="dbdoclet.50569350_89622" /> must be implemented.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="req_illan_attributes_checksum_offload_3">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_37925"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Checksum Offload Support option:</emphasis> When
the caller of H_SEND_LOGICAL_LAN has set the No Checksum bit in the
Control field to a 1, then they must also have set the checksum field in
the packet to 0, unless bit 46 in the ILLAN Attributes (the "Checksum Offload Non-zero
Checksum Field Support" bit) is set.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569350_39278">
<title>Checksum Offload Padded Packet Support Option</title>
<para>Firmware may or may not support checksum offload for IPv4 packets
that have been padded. The Checksum Offload Padded Packet Support bit of
the ILLAN Attributes specifies whether or not this option is
supported.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_39278"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Checksum Offload Padded Packet Support
Option:</emphasis> The platform must do all the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Implement the ILLAN Checksum Offload Support option.</para>
</listitem>
<listitem>
<para>Implement the Checksum Offload Padded Support bit of the ILLAN
Attributes, as defined in
<xref linkend="dbdoclet.50569350_11661" />, and set that bit to a value
of 1.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569350_39077">
<title>ILLAN Buffer Size Control Option</title>
<para>It is the partition software&#8217;s responsibility to keep
firmware supplied with enough buffers to keep packets from being dropped.
The ILLAN Buffer Size Control option gives the partition software a way
to prevent a flood of small packets from consuming buffers that have been
allocated for larger packets.</para>
<para>When this option is implemented and the Buffer Size Control bit in
the ILLAN Attributes is set to a 1 for the VLAN, the hypervisor will keep
a history of what buffer sizes have been registered. Then, when a packets
arrives the history is searched to find the smallest buffer size that
will contain the packet. If that buffer size is depleted then the packet
is dropped by the hypervisor (H_Dropped) instead of searching for the
next larger available buffer.</para>
<section>
<title>General</title>
<para>The following are the general requirements for this option. For
H_SEND_LOGICAL_LAN changes, see
<xref linkend="dbdoclet.50569350_37925" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_39077"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Buffer Size Control option:</emphasis> The
platform must do all the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Implement the ILLAN option.</para>
</listitem>
<listitem>
<para>Implement the H_ILLAN_ATTRIBUTES hcall().</para>
</listitem>
<listitem>
<para>Implement the
<emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis> property in the
VIOA&#8217;s Device Tree node.</para>
</listitem>
<listitem>
<para>Implement the Buffer Size Control bit of the ILLAN Attributes,
as defined in
<xref linkend="dbdoclet.50569350_11661" />.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569350_37925.1">
<title>H_SEND_LOGICAL_LAN Semantic Changes</title>
<para>The following are the required semantic changes to the
H_SEND_LOGICL_LAN hcall().</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569350_37925.1"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Buffer Size Control option:</emphasis> When the
Buffer Size Control bit of the target of an H_SEND_LOGIC_LAN hcall() is
set to a 1, then the firmware for the H_SEND_LOGICAL_LAN hcall() must not
just search for any available buffer into which the packet will fit, but
must instead only place the packet into the receiver&#8217;s buffer if
there is an available buffer of the smallest size previously registered
by the receiver which will fit the packet, and must drop the packet for
that target otherwise.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="sec_illan_large_send_indication">
<title>ILLAN Large Send/Receive option</title>
<para>This option allows the virtual device to send an
indication to the receiver that the data being sent by
H_SEND_LOGICAL_LAN contains a large send packet.</para>
<section xml:id="sec_illan_large_send_indication_general">
<title>General</title>
<para>The following are the general requirements for this option. For H_SEND_LOGICAL_LAN changes, see
<xref linkend="sec_send_logical_lan_semantic_change" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_illan_large_send_indication_general"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Large send indication option:</emphasis>
The platform must do all the following:</para>
<orderedlist numeration="loweralpha" spacing="compact">
<listitem>
<para>Implement the H_ILLAN_ATTRIBUTES hcall().</para>
</listitem>
<listitem>
<para>Implement the Large Send Indication bit of the ILLAN Attributes as defined in
<xref linkend="dbdoclet.50569350_11661" />.</para>
</listitem>
<listitem>
<para>Handle the large send/receive enabled bit being set in the
ILLAN Attributes set mask as defined in
<xref linkend="dbdoclet.50569350_11661" />.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_send_logical_lan_semantic_change">
<title>H_SEND_LOGICAL_LAN Semantic Changes</title>
<para>The following are the required semantic changes to the H_SEND_LOGICAL_LAN hcall().</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_send_logical_lan_semantic_change"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the ILLAN Large send indication option:</emphasis>
When the Large Send Indication bit of the first buffer descriptor is set to 1,
then the firmware for the H_SEND_LOGICAL_LAN hcall() must set the Large
Send Indication bit in the receiver's receive queue entry to 1 when the
packet is copied to the destination receive buffer and examine the MSS
parameter. If the MSS is greater than 0 and the both the sender and
receiver have enabled large send/receive using H_ILLAN_ATTRIBUTES,
firmware will copy the MSS into the receive buffer.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_illan_receive_buffer">
<title>Receive Buffer</title>
<para>Bit 5 in the Receive Queue entry indicates that the buffer contains a
large-send packet. The software device driver should inspect the 8-byte
value at byte offset 8 of the receive buffer for the MSS. If that value is 0,
the MSS is stored in the packet itself. In the case that the buffer contains
a large-send packet, the Ipv4 checksum can be considered good and does not
need to be verified.</para>
</section>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569351_35753">
<title>Virtual SCSI (VSCSI)</title>
<para>Virtual SCSI (VSCI) support is provided by code running in a server
partition that uses the mechanisms of the Reliable Command/Response
Transport and Logical Remote DMA of the Synchronous VIO Infrastructure to
service I/O requests for code running in a client partition, such that, the
client partition appears to enjoy the services of its own SCSI adapter (see
<xref linkend="dbdoclet.50569348_51946" />). The terms server and client
partitions refer to platform partitions that are respectively servers and
clients of requests, usually I/O operations, using the physical I/O
adapters (IOAs) that are assigned to the server partition. This allows a
platform to have more client partitions than it may have physical I/O
adapters because the client partitions share I/O adapters via the server
partition.</para>
<para>The VSCSI architecture is built upon the architecture specified in
the following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
<section xml:id="dbdoclet.50569351_81654">
<title>VSCSI General</title>
<para>This section contains an informative outline of the architectural
intent of the use of the Synchronous VIO Infrastructure to provide VSCSI
support, along with a few architectural requirements. Other
implementations of the server and client partition code, consistent with
this architecture, are possible and may be preferable.</para>
<para>The architectural metaphor for the VSCSI subsystem is that the
server partition provides the virtual equivalent of a single SCSI
DASD/Media string via each VSCSI server virtual IOA. The client partition
provides the virtual equivalent of a single port SCSI adapter via each
VSCSI client IOA. The platform, through the partition definition,
provides means for defining the set of virtual IOA&#8217;s owned by each
partition and their respective location codes. The platform also
provides, through partition definition, instructions to connect each
client partition&#8217;s VSCSI client IOA to a specific server
partition&#8217;s VSCSI server IOA. That is, the equivalent of connecting
the adapter cable to the specific DASD/Media string. The mechanism for
specifying this partition definition is beyond the scope of this
architecture. The human readable handle associated with the partition
definition of virtual IOAs and their associated interconnection and
resource configuration is the virtual location code. The OF unit address
(<emphasis role="bold"><literal>Unit ID</literal></emphasis>) remains the invariant handle upon which the
OS builds its &#8220;physical to logical&#8221; configuration.</para>
<para>The client partition&#8217;s device tree contains one or more nodes
notifying the partition that it has been assigned one or more virtual
adapters. The node&#8217;s
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> properties notify the
partition that the virtual adapter is a VSCSI adapter. The
<emphasis role="bold">unit address</emphasis> of the node is used by the client
partition to map the virtual device(s) to the OS&#8217;s corresponding
logical representations. The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property communicates
the size of the RTCE table window panes that the hypervisor has
allocated. The node also specifies the interrupt source number that has
been assigned to the Reliable Command/Response Transport connection and
the RTCE range that the client partition device driver may use to map its
memory for access by the server partition via Logical Remote DMA. The
client partition, uses the four hcall()s associated with the Reliable
Command/Response Transport facility to register and deregister its CRQ,
manage notification of responses, and send command requests to the server
partition.</para>
<para>The server partition&#8217;s device tree contains one or more
node(s) notifying the partition that it is requested to supply VSCSI
services for one or more client partitions. The unit address (
<emphasis role="bold"><literal>Unit ID</literal></emphasis>) of the node is used by the server partition
to map to the local logical devices that are represented by this VSCSI
device. The node also specifies the interrupt source number that has been
assigned to the Reliable Command/Response Transport connection and the
RTCE range that the server partition device driver may use for its copy
Logical Remote DMA. The server partition uses the four hcall()s
associated with the Reliable Command/Response Transport facility to
register and deregister its Command request queue, manage notification of
new requests, and send responses back to the client partition. In
addition, the server partition uses the hcall()s of the Logical Remote
DMA facility to manage the movement of commands and data associated with
the client requests.</para>
<para>The client partition, upon noting the device tree entry for the
virtual adapter, loads the device driver associated with the value of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property. The device driver,
when configured and opened, allocates memory for its CRQ (an array, large
enough for all possible responses, of 16 byte elements), pins the queue
and maps it into the I/O space of the RTCE window specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property using the
standard kernel mapping services that subsequently use the H_PUT_TCE
hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next,
I/O request control blocks (within which the I/O requests commands are
built) are allocated, pinned, and mapped into I/O address space. Finally,
the device driver registers to receive control when the interrupt source
specified in the virtual IOA&#8217;s device tree node signals.</para>
<para>Once the CRQ is setup, the device driver queues an Initialization
Command/Response with the second byte of &#8220;Initialize&#8221; in
order to attempt to tell the hosting side that everything is setup on the
hosted side. The response to this send may be that the send has been
dropped or has successfully been sent. If successful, the sender should
expect back an Initialization Command/Response with a second byte of
&#8220;Initialization Complete,&#8221; at which time the communication
path can be deemed to be open. If dropped, then the sender waits for the
receipt of an Initialization Command/Response with a second byte of
&#8220;Initialize,&#8221; at which time an &#8220;Initialization
Complete&#8221; message is sent, and if that message is sent
successfully, then the communication path can be deemed to be
open.</para>
<para>When the VSCSI Adapter device driver receives an I/O request from
one of the SCSI device head drivers, it executes the following sequence.
First an I/O request control block is allocated. Then it builds the SCSI
request within the control block, adds a correlator field (to be returned
in the subsequent response), I/O maps any target memory buffers and
places their DMA descriptors into the I/O request control block. With the
request constructed in the I/O request control block, the driver
constructs a DMA descriptor (Starting Offset, and length) representing
the I/O request within the I/O request control block. Lastly, the driver
passes the I/O request&#8217;s DMA descriptor to the server partition
using the H_SEND_CRQ hcall(). Provided that the H_SEND_CRQ hcall()
succeeds, the VSCSI Adapter device driver returns, waiting for the
response interrupt indicating that a response has been posted by the
server partition to the device driver&#8217;s response queue. The
response queue entry contains the summary status and request correlator.
From the request correlator, the device driver accesses the I/O request
control block, and from the summary status, the device driver determines
how to complete the processing of the I/O request.</para>
<para>Notice that the client partition only uses the Reliable
Command/Response Transport primitives; it does not use the Logical Remote
DMA primitives. Since the server partition&#8217;s RTCE tables are not
authorized for access by the client partition, any attempt by the client
partition to modify server partition memory would be prevented by the
hypervisor. RTCE table access is granted on a connection by connection
basis (client/server virtual device pair). If a client partition happens
to be serving some other logical device, then the partition is entitled
to use Logical Remote DMA for the virtual devices that is serving.</para>
<para>The server partition, upon noting the device tree entry for the
virtual adapter, loads the device driver associated with the value of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property. The device driver,
when configured and opened, allocates memory for its request queue (an
array, large enough for all possible outstanding requests, of 16 byte
elements). The driver then pins the queue and maps it into I/O space, via
the kernel&#8217;s I/O mapping services that invoke the H_PUT_TCE
hcall(), using the first window pane specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. The queue
is then registered using the H_REG_CRQ hcall(). Next, I/O request control
blocks (within which the I/O request commands are built) are allocated,
pinned, and I/O mapped. Finally the device driver registers to receive
control when the interrupt source specified in the virtual IOA&#8217;s
device tree node signals.</para>
<para>Once the CRQ is setup, the device driver queues an Initialization
Command/Response with the second byte of &#8220;Initialize&#8221; in
order to attempt to tell the hosted side that everything is setup on the
hosting side. The response to this send may be that the send has been
dropped or has successfully been sent. If successful, the sender should
expect back an Initialization Command/Response with a second byte of
&#8220;Initialization Complete,&#8221; at which time the communication
path can be deemed to be open. If dropped, then the sender waits for the
receipt of an Initialization Command/Response with a second byte of
&#8220;Initialize,&#8221; at which time an &#8220;Initialization
Complete&#8221; message is sent, and if that message is sent
successfully, then the communication path can be deemed to be
open.</para>
<para>When the server partition&#8217;s device driver receives an I/O
request from its corresponding client partition&#8217;s VSCSI adapter
drivers, it is notified via the interrupt registered for above. The
server partition&#8217;s device driver selects an I/O request control
block for the requested operation. It then uses the DMA descriptor from
the request queue element to transfer the SCSI request from the client
partition&#8217;s I/O request control block to its own (allocated above),
using the H_COPY_RDMA hcall() through the second window pane specified in
the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. The server
partition&#8217;s device driver then uses kernel services, that are
extended, to register the I/O request&#8217;s DMA descriptors into
extended capacity cross memory descriptors (ones capable of recording the
DMA descriptors). These cross memory descriptors are later mapped by the
server partition&#8217;s physical device drivers into the physical I/O
DMA address space of the physical I/O adapters using the kernel services,
that have been similarly extended to call the H_PUT_RTCE hcall(), based
upon the value of the LIOBN field reference by the cross memory
descriptor. At this point, the server partition&#8217;s VSCSI device
driver delivers what appears to be a SCSI request to be decoded and
routed through the server partition&#8217;s file sub-system for
processing. When the request completes, the server partition&#8217;s
VSCSI device driver is called by the file sub-system and it packages the
summary status along with the request correlator into a response message
that it sends to the client partition using the H_SEND_CRQ hcall(), then
recycles the resources recorded in the I/O request control block, and the
block itself.</para>
<para>The LIOBN value in the second window pane of the server
partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property is intended
to be an indirect reference to the RTCE table of the client partition.
If, for some reason, the physical location of the client
partition&#8217;s RTCE table changes or it becomes invalid, this level of
indirection allows the hypervisor to determine the current target without
changing the LIOBN number as seen by the server partition. The H_PUT_TCE
and H_PUT_RTCE hcall()s do not map server partition memory into the
second window pane; the second window pane is only available for use by
server partition via the Logical RDMA services to reference memory mapped
into it by the client partition&#8217;s IOA.</para>
<para>This architecture does not specify the payload format of the
requests or responses. However, the architectural intent is supplied in
the following tables for reference.</para>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>General Form of Reliable CRQ Element</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="55*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Subfield Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Header</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Contains Element Valid Bit plus Event Type Encodings (see
<xref linkend="dbdoclet.50569348_49382" />).</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry morerows="1">
<para>Payload</para>
</entry>
<entry>
<para>Format/Transport Event Code</para>
</entry>
<entry>
<para>For Valid Command Response Entries, see
<xref linkend="dbdoclet.50569351_41722" />. For Transport Event
Codes see
<xref linkend="dbdoclet.50569348_93265" />.</para>
</entry>
</row>
<row>
<entry>
<para>2-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Format Dependent.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569351_41722">
<title>Example Reliable CRQ Entry Format Byte Definitions for VSCSI</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">Format Byte Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>VSCSI Requests</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>VSCSI Responses</para>
</entry>
</row>
<row>
<entry>
<para>0x03 - 0xFE</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Example VSCSI Command Queue Element</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>VSCSI Request Format</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>4-7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Length of the request block to be transferred</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>I/O address of beginning of request</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Example VSCSI Response Queue Element</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>VSCSI Response Format</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>4-7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Summary Status</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>8 byte command correlator</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>See also
<xref linkend="dbdoclet.50569379_75285" />.</para>
</section>
<section xml:id="sec_vscsi_req">
<title>Virtual SCSI Requirements</title>
<para>This normative section provides the general requirements for the
support of VSCSI.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vscsi_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform must implement the
Reliable Command/Response Transport option as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vscsi_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform must implement the
Logical Remote DMA option as defined in
<xref linkend="dbdoclet.50569348_61656" />.</para>
<para>In addition to the firmware primitives, and the structures they
define, the partition&#8217;s OS needs to know specific information
regarding the configuration of the virtual IOA&#8217;s that it has been
assigned so that it can load and configure the correct device driver
code. This information is provided by the OF device tree node associated
with the virtual IOA (see
<xref linkend="dbdoclet.50569351_34050" /> and
<xref linkend="dbdoclet.50569351_74366" />).</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569351_34050">
<title>Client Partition Virtual SCSI Device Tree Node</title>
<para>Client partition VSCSI device tree nodes have associated packages
such as disk-label, deblocker, iso-13346-files and iso-9660-files as well
as children nodes such as block and byte as appropriate to the specific
virtual IOA configuration as would the node for a physical IOA of type
scsi-3.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569351_34050"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform&#8217;s OF device
tree for client partitions must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, a node of name &#8220;v-scsi&#8221; as
the parent of a sub-tree representing the virtual IOAs assigned to the
partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569351_34050"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>v-scsi</literal></emphasis> OF node must contain properties as defined in
<xref linkend="dbdoclet.50569351_40283" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Properties of the VSCSI Node in the Client
Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name, the
value shall be
<emphasis role="bold"><literal>&#8220;v-scsi&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type, the
value shall be
<emphasis role="bold"><literal>&#8220;vscsi&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA, the value shall include
<emphasis role="bold"><literal>&#8220;IBM,v-scsi&#8221;</literal></emphasis>.
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-2&#8221;</literal></emphasis> precedes
<emphasis role="bold"><literal>&#8220;IBM,vsci&#8221;</literal></emphasis> if it is included in
the value of this property.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of three values
(LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall().</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569351_34050"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>v-scsi</literal></emphasis> node must have as children the appropriate
block (<emphasis role="bold"><literal>disk</literal></emphasis>) and byte
(<emphasis role="bold"><literal>tape</literal></emphasis>) nodes.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569351_74366">
<title>Server Partition Virtual SCSI Device Tree Node</title>
<para>Server partition VSCSI IOA nodes have no children nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569351_74366"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform&#8217;s OF device
tree for server partitions must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, a node of name
<emphasis role="bold"><literal>&#8220;v-scsi-host&#8221;</literal></emphasis> as the parent of a sub-tree
representing the virtual IOAs assigned to the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569351_74366"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSCSI option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>v-scsi-host</literal></emphasis> node must contain properties as defined
in
<xref linkend="dbdoclet.50569351_40283" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569351_40283">
<title>Properties of the VSCSI Node in the Server
Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name, the
value shall be
<emphasis role="bold"><literal>&#8220;v-scsi-host&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type, the
value shall be
<emphasis role="bold"><literal>&#8220;v-scsi-host&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA, the value shall include
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-host&#8221;</literal></emphasis>.
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-host-2&#8221;</literal></emphasis> precedes
<emphasis role="bold"><literal>&#8220;IBM,vsci-host&#8221;</literal></emphasis> if it is
included in the value of this property.
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of two sets (two
window panes) of three values (LIOBN, phys, size) encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>. Of these two triples, the
first describes the window pane used to map server partition
memory, the second is the window pane through which the client
partition maps its memory that it makes available to the server
partition. (Note the mapping between the LIOBN in the second
window pane of a server virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property
and the corresponding client IOA&#8217;s RTCE table is made
when the CRQ successfully completes registration. See
<xref linkend="dbdoclet.50569348_40629" /> for more information
on window panes.)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall()</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vserver&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying that this is a virtual server
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569352_15379">
<title>Virtual Terminal (Vterm)</title>
<para>This section defines the Virtual Terminal (Vterm) options (Client
Vterm option and Server Vterm option). Vterm IOAs are of the hypervisor
simulated class of VIO. See also
<xref linkend="dbdoclet.50569375_64200" />.</para>
<section>
<title>Vterm General</title>
<para>This section contains an informative outline of the architectural
intent of the use of Vterm support.</para>
<para>The architectural metaphor for the Vterm IOA is that of an Async
IOA. The connection at the other end of the Async &#8220;cable&#8221; may
be another Vterm IOA in a server partition, the hypervisor, or the
HMC.</para>
<para>A partition&#8217;s device tree contains one or more nodes
notifying the partition that it has been assigned one or more Vterm
client adapters (each LoPAR partition has at least one). The
node&#8217;s
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> properties notify the
partition that the virtual adapter is a Vterm client adapter. The
<emphasis role="bold"><literal>unit address</literal></emphasis> of the node is used by the partition to
map the virtual device(s) to the OS&#8217;s corresponding logical
representations. The node&#8217;s
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property, if it exists,
specifies the interrupt source number that has been assigned to the
client Vterm IOA for receive data. The partition, uses the
H_GET_TERM_CHAR and H_PUT_TERM_CHAR hcall()s to receive data from and
send data to the client Vterm IOA. If the node contains the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property, the partition may
optionally use the
<emphasis>ibm,int-on</emphasis>,
<emphasis>ibm,int-off</emphasis>,
<emphasis>ibm,set-xive, ibm,get-xive</emphasis> RTAS calls, and the
H_VIO_SIGNAL hcall() to manage the client Vterm IOA interrupt.</para>
<para>A partition&#8217;s device tree may also contain one or more
node(s) notifying the partition that it is requested to supply server
Vterm IOA services for one or more client Vterm IOAs. The node&#8217;s
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> properties notify the
partition that the virtual adapter is a server Vterm IOA. The unit
address (<emphasis role="bold"><literal>Unit ID</literal></emphasis>) of the node is used by the partition to map
the virtual device(s) to the OS&#8217;s corresponding logical
representations. The node&#8217;s
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property specifies the
interrupt source number that has been assigned to the server Vterm IOA
for receive data. The partition uses the H_VTERM_PARTNER_INFO hcall() to
find out which unit address(es) in which partition(s) to which it is
allowed to attach (that is, to which client Vterm IOAs it is allowed to
attach). The partition then uses the H_REGISTER_VTERM to setup the
connection between a server and a client Vterm IOAs, and uses the
H_GET_TERM_CHAR and H_PUT_TERM_CHAR hcall()s to receive data from and
send data to the server Vterm IOA. In addition, the partition may
optionally use the
<emphasis>ibm,int-on</emphasis>,
<emphasis>ibm,int-off</emphasis>,
<emphasis>ibm,set-xive, ibm,get-xive</emphasis> RTAS calls, and the
H_VIO_SIGNAL hcall() to manage the server Vterm IOA interrupt.</para>
<para>
<xref linkend="dbdoclet.50569352_52094" /> shows a comparison between the
client and server versions of Vterm.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569352_52094">
<title>Client Vterm versus Server Vterm Comparison</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Client</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Server</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry nameend="c2" namest="c1">
<para>The following hcall()s apply:<?linebreak?>
H_PUT_TERM_CHAR<?linebreak?>
H_GET_TERM_CHAR<?linebreak?>
H_VIO_SIGNAL (optional use with Client)</para>
</entry>
</row>
<row>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>The following hcall()s are valid:<?linebreak?>
H_VTERM_PARTNER_INFO<?linebreak?>
H_REGISTER_VTERM<?linebreak?>
H_FREE_VTERM</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>vty</literal></emphasis> node</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>vty-server</literal></emphasis> node</para>
</entry>
</row>
<row>
<entry>
<para>The
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property or the
<emphasis role="bold"><literal>vty</literal></emphasis> node(s)</para>
<para>enumerates the valid client Vterm IOA unit
address(es)</para>
</entry>
<entry>
<para>The
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property or the
<emphasis role="bold"><literal>vty-server</literal></emphasis> node(s) enumerates the valid server Vterm IOA unit
address(es)</para>
<para>H_VTERM_PARTNER_INFO is used to getvalid client Vterm IOA partition ID(s) and corresponding
unit address(es) to which the server Vterm IOA is allowed to
connect</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property
optional:</para>
<para>Platform may or may not provide<?linebreak?>
If provided, Vterm driver may or may not use</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property
required:</para>
<para>Platform must provide<?linebreak?>
If provided, Vterm driver may or may not use</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vterm_req">
<title>Vterm Requirements</title>
<para>This normative section provides the general requirements for the
support of Vterm.</para>
<variablelist xml:id="dbdoclet.50569352_15774">
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vterm_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LPAR option:</emphasis>
the Client Vterm option must be implemented.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Character Put and Get hcall()s</title>
<para>The following hcall()s are used to send data to and get data from
both the client and sever Vterm IOAs.</para>
<section xml:id="dbdoclet.50569352_18926">
<title>H_GET_TERM_CHAR</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[uint64 hcall ( const uint64 H_GET_TERM_CHAR, int64 termno );]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>termno: The unit address of the Vterm IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of the Vterm IOA.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the termno parameter for validity against the
Vterm IOA unit addresses assigned to the partition, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Hardware if it detects that the virtual
console terminal physical connection is not working.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Closed if it detects that the virtual
console associated with the termno parameter is not open (in the case of
connection to a server Vterm IOA, this means that the server code has not
made the connection to this specific client Vterm IOA).</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Success in all other cases, returning
maximum number of characters available in the partition&#8217;s virtual
console terminal input buffer (up to 16) -- a len value of 0 indicates
that the input buffer is empty.</para>
</listitem>
<listitem>
<para>Upon return with H_Success register R4 contains the number of
bytes (if any) returned in registers R5 and R6.</para>
</listitem>
<listitem>
<para>Upon return with H_Success the return character string starts in
the high order byte of register R5 and proceeds toward the low order byte
in register R6 for the number of characters specified in R4. The contents
of all other byte locations of registers R5 and R6 are undefined.</para>
</listitem>
<listitem>
<para>Upon return with H_Success register R4 contains the number of
bytes (if any) returned in registers R5 and R6.</para>
</listitem>
<listitem>
<para>Upon return with H_Success the return character string starts in
the high order byte of register R5 and proceeds toward the low order byte
in register R6 for the number of characters specified in R4. The contents
of all other byte locations of registers R5 and R6 are undefined.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569352_36115">
<title>H_PUT_TERM_CHAR</title>
<para />
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 hcall ( const uint64 H_PUT_TERM_CHAR, int64 termno, int64 len, unit64 char0_7,
init64 char8_15);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>termno: The unit address of the Vterm IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of the Vterm IOA.</para>
</listitem>
<listitem>
<para>len: The length of the string to transmit through the virtual
terminal port. Valid values are in the range of 0-16.</para>
</listitem>
<listitem>
<para>char0_7 and char8_15: The string starts in the high order byte of
register R6 and proceeds toward the low order byte in register R7</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the termno parameter for validity against the
Vterm IOA unit addresses assigned to the partition, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Hardware if it detects that the virtual
console terminal physical connection is not working.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Closed if it detects that the virtual
console session is not open (in the case of connection to a server Vterm
IOA, this means that the server code has not made the connection to this
specific client Vterm IOA).</para>
</listitem>
<listitem>
<para>If the length parameter is outside of the values 0-16 the
hypervisor immediately returns H_Parameter with no other action.</para>
</listitem>
<listitem>
<para>If the partition&#8217;s virtual console terminal buffer has room
for the entire string, the hypervisor queues the output string and
returns H_Success.
<emphasis role="bold">Note:</emphasis> There is always room for a zero length string (a
zero length write can be used to test the virtual console terminal
connection).</para>
</listitem>
<listitem>
<para>If the buffer cannot hold the entire string, no data is enqueued
and the return code is H_Busy.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="sec_interrupts">
<title>Interrupts</title>
<para>The interrupt source number is presented in the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property of the
<emphasis role="bold"><literal>Vterm</literal></emphasis> node, when receive queue interrupts are
implemented for the Vterm. The
<emphasis>ibm,int-on</emphasis>,
<emphasis>ibm,int-off</emphasis>,
<emphasis>ibm,set-xive, ibm,get-xive</emphasis> RTAS calls, and
H_VIO_SIGNAL hcall() are used to manage the interrupt.</para>
<para>Interrupts and the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property are always
implemented for the server Vterm IOA, and may be implemented for the
client Vterm IOA.</para>
<para>The interrupt mechanism is edge-triggered and is capable of
presenting only one interrupt signal at a time from any given interrupt
source. Therefore, no additional interrupts from a given source are ever
signaled until the previous interrupt has been processed through to the
issuance of an H_EOI hcall(). Specifically, even if the interrupt mode is
enabled, the effect is to interrupt on an empty to non-empty transition
of the receiver queue or upon the closing of the connection between the
server and client. However, as with any asynchronous posting operation
race conditions are to be expected. That is, an enqueue can happen in a
window around the H_EOI hcall() so that the receiver should poll the
receive queue after an H_EOI using H_GET_TERM_CHAR after an H_EOI, to
prevent losing initiative.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_interrupts"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Server Vterm option:</emphasis> The platform must
implement the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property in all server
<emphasis role="bold"><literal>Vterm</literal></emphasis> device tree nodes (
<emphasis role="bold"><literal>vty-server</literal></emphasis>), and must set the interrupt in that
property for the receive data interrupt for the IOA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_interrupts"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Client Vterm and Server Vterm options:</emphasis> When
implemented, the characteristics of the Vterm interrupts must be as
follows:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>All must be edge-triggered.</para>
</listitem>
<listitem>
<para>The receive interrupt must be activated when the Vterm receive
queue goes from empty to non-empty.</para>
</listitem>
<listitem>
<para>The receive interrupt must be activated when the Vterm
connection from the client to the server goes from open to closed.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569352_34050">
<title>Client Vterm Device Tree Node (vty)</title>
<para>All platforms that implement LPAR, also implement at least one
client Vterm IOA per partition.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569352_34050"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Client Vterm option:</emphasis> The H_GET_TERM_CHAR and
H_TERM_CHAR hcall()s must be implemented.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569352_34050"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Client Vterm option:</emphasis> The platform&#8217;s OF
device tree must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, one or more nodes of type
&#8220;vty&#8221;; one for each client Vterm IOA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569352_34050"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Client Vterm option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vty</literal></emphasis> OF node must contain properties as defined in
<xref linkend="dbdoclet.50569352_21738" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569352_21738">
<title>Properties of the
<emphasis role="bold"><literal>vty</literal></emphasis> Node (Client Vterm IOA)</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name. The
value shall be
<emphasis role="bold"><literal>&#8220;vty&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type. The
value shall be
<emphasis role="bold"><literal>&#8220;serial&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA. The value shall include
<emphasis role="bold"><literal>&#8220;hvterm1&#8221;</literal></emphasis> when the virtual IOA
will connect to a server with no special protocol, and shall
include
<emphasis role="bold"><literal>&#8220;hvterm-protocol&#8221;</literal></emphasis> when the
virtual IOA will connect to a server that requires a protocol
to control modems or hardware control signals.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall(). If provided, this property will present one interrupt;
the receive data interrupt.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569352_34050"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Client Vterm option:</emphasis> If the compatible
property in the
<emphasis role="bold"><literal>vty</literal></emphasis> node is
<emphasis role="bold"><literal>&#8220;hvterm-protocol&#8221;</literal></emphasis>, then the protocol
that the client must use is defined in the document entitled
<emphasis>Protocol for Support of Physical Serial Port Using a Virtual
TTY Interface</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569352_74366">
<title>Server Vterm</title>
<para>Server Vterm IOAs allow a partition to serve a partner
partition&#8217;s client Vterm IOA.</para>
<section xml:id="sec_vterm_node_req">
<title>Server Vterm Device Tree Node (vty-server) and Other
Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vterm_node_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Server Vterm option:</emphasis> The H_GET_TERM_CHAR,
H_PUT_TERM_CHAR, H_VTERM_PARTNER_INFO, H_REGISTER_VTERM, and H_FREE_VTERM
hcall()s must be implemented.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vterm_node_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Server Vterm option:</emphasis> The platform&#8217;s OF
device tree for partitions implementing server Vterm IOAs must include as
a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, one or more nodes of type
<emphasis role="bold"><literal>&#8220;vty-server&#8221;</literal></emphasis>; one for each server Vterm
IOA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vterm_node_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Server Vterm option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vty-server</literal></emphasis> node must contain properties as defined in
<xref linkend="dbdoclet.50569352_40283" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569352_40283">
<title>Properties of the
<emphasis role="bold"><literal>vty-server</literal></emphasis> Node (Server Vterm IOA)</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name. The
value shall be
<emphasis role="bold"><literal>&#8220;vty-server&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type. The
value shall be
<emphasis role="bold"><literal>&#8220;serial-server&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA. The value shall include
<emphasis role="bold"><literal>&#8220;hvterm2&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length specified by
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall(). This property will present one interrupt; the receive
data interrupt.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vserver&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying that this is a virtual server
node.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Server Vterm hcall()s</title>
<para>The following hcall()s are unique to the server Vterm IOA.</para>
<section xml:id="dbdoclet.50569352_31370">
<title>H_VTERM_PARTNER_INFO</title>
<para>This hcall is used to retrieve the list of Vterms to which the
specified server Vterm IOA is permitted to connect. The list is retrieved
by making repeated calls, and returns sets of triples: partner partition
ID, partner unit address, and partner location code. Passing in the
previously returned value will return the next value in the list of
allowed connections. Passing in a value of 0xFF...FF will return the
first value in the list.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections */
uint64 unit-address, /* As specified in the Virtual IOA’s device tree node */
uint64 partner-partition-id, /* The last partner partition ID returned, or */
/* 0xFF...FF to start */
uint64 partner-unit-addr /* The last partner unit address returned, or */
/* 0xFF...FF to start */
uint64 buffr-addr /* The logical address of the buffer where */
/* the data is to be returned */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Virtual IOA&#8217;s unit address, as specified in
the IOA&#8217;s device tree node.</para>
</listitem>
<listitem>
<para>partner-partition-id: The partner partition ID of the last
partner partition ID and partner unit address pair returned. If a value
of 0xFF...FF is specified, the call returns the first item in the
list.</para>
</listitem>
<listitem>
<para>partner-unit-addr: The partner unit address of the last partner
partition ID and partner unit address pair returned. If a value of
0xFF...FF is specified, the call returns the first item in the
list.</para>
</listitem>
<listitem>
<para>buffr-addr: The logical address of a single page in memory,
belonging to the calling partition, which is used to return the next
triple of information (partner partition ID, partner unit address, and
Converged Location Code). The calling partition cannot migrate the page
during the duration of the call, otherwise the call will fail.</para>
<para>Buffer format on return with H_Success:</para>
</listitem>
<listitem>
<para>First eight bytes: Eight byte partner partition ID of the partner
partition ID and partner unit address pair from the list, or 0xFF...FF if
partner partition ID and partner unit address passed in the input
parameters was the last item in the list of valid connections.</para>
</listitem>
<listitem>
<para>Second eight bytes: Eight byte partner unit address associated
with the partner partition ID (as returned in first 8 bytes of the
buffer), or 0xFF...FF if the partner partition ID and partner unit
address passed in the input parameters was the last item in the list of
valid connections.</para>
</listitem>
<listitem>
<para>Beginning at the 17 byte in the buffer: NULL-terminated Converged
Location Code associated with the partner unit address and partner
partition ID (a returned in the first 16 bytes of the buffer), or just a
NULL string if the partner partition ID and partner unit address passed
in the input parameters was the last item in the list of valid
connections.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that unit-address belongs to the partition and to a
server Vterm IOA, else H_Parameter.</para>
</listitem>
<listitem>
<para>If partner-partition-id and partner-unit-addr together do not
match a valid partner partition ID and partner unit address pair in the
list of valid connections for this unit-address, then return
H_Parameter.</para>
</listitem>
<listitem>
<para>If the 4 KB page associated with buffr-addr does not belong to
the calling partition, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If the buffer associated with buffr-addr does not begin on a 4 K
boundary, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If the calling partition attempts to migrate the buffer page
associated with buffr-addr during the duration of the
H_VTERM_PARTNER_INFO call, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If partner-partition-id is equal to 0xFF...FF, then select the
first item from the list of valid connections, format the buffer as
specified, above, for this item, and return H_Success.</para>
</listitem>
<listitem>
<para>If partner-partition-id and partner-unit-addr together matches a
valid partner partition ID and partner unit address pair in the list of
valid connections, and if this is the last valid connection in the list,
then format the buffer as specified, above, with the partner partition ID
and partner unit address both set to 0xFF...FF, and the Converged
Location Code set to the NULL string, and return H_Success.</para>
</listitem>
<listitem>
<para>If partner-partition-id and partner-unit-addr together matches a
valid partner partition ID and partner unit address pair in the list of
valid connections, then select the next item from the list of valid
connections, and format the buffer as specified, above, and return
H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="dbdoclet.50569352_39886">
<title>H_REGISTER_VTERM</title>
<para>This hcall has the effect of &#8220;opening&#8221; the connection
to the client Vterm IOA in the specified partition ID and which has the
specified unit address. The architectural metaphor for this is the
connecting of the cable between two Async IOAs. The hcall fails if the
partition does not have the authority to connect to the requested
partition/unit address pair. The hcall() also fails if the specified
partition/unit address is already in use (for example, by another
partition or the HMC)</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
hcall ( const uint64 H_REGISTER_VTERM, /* Makes connection between server and */
/* partner Vterm IOAs */
uint64 unit-address, /* As specified in the Virtual IOA’s device */
/* tree node */
uint64 partner-partition-id, /* The partner ID to which to be connected */
uint64 partner-unit-addr /* The partner unit address to which to be */
/* connected */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: The server Virtual IOA&#8217;s unit address, as
specified in the IOA&#8217;s device tree node.</para>
</listitem>
<listitem>
<para>partner-partition-id: The partition ID of the partition ID and
unit address pair to which to be connected.</para>
</listitem>
<listitem>
<para>partner-unit-addr: The unit address of the partition ID and unit
address pair to which to be connected.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that unit-address belongs to the partition and to a
server Vterm IOA and that there does not exist a valid connection between
this server Vterm IOA and a partner, else H_Parameter.</para>
</listitem>
<listitem>
<para>If partner-partition-id and partner-unit-addr together do not
match a valid partition ID and unit address pair in the list of valid
connections for this unit-address, then return H_Parameter,</para>
<itemizedlist>
<listitem>
<para>Else make connection between the server Vterm IOA specified by
unit-address and the client Vterm IOA specified by the
partner-partition-id and partner-unit-addr pair, allowing future
H_PUT_TERM_CHAR and H_GET_TERM_CHAR operations to flow between the two
Vterm IOAs, and return H_Success.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Software Implementation Note:</emphasis> An H_Parameter will be
returned to the H_REGISTER_VTERM if a DLPAR operation has been performed
which changes the list of possible server to client Vterm connections.
After a DLPAR operation which affects a partition&#8217;s server Vterm
IOA connection list, a call to H_VTERM_PARTNER_INFO is needed to get the
current list of possible connections.</para>
</simplesect>
</section>
<section xml:id="dbdoclet.50569352_49502">
<title>H_FREE_VTERM</title>
<para>This hcall has the effect of &#8220;closing&#8221; the connection
to the partition/unit address pair. The architectural metaphor for this
is the removal of the cable between two Async IOAs. After closing, the
partner partition&#8217;s server Vterm IOA would now be available for
serving by another partner (for example, another partition or the
HMC).</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected Return code */
/* H_Parameter: One or more of the parameters are invalid */
/* H_Hardware: The function failed due to unrecoverable */
/* hardware failure. */
/* H_Busy: Try, again */
/* H_LongBusyOrder1mSec: Try again (hint: may be up to 1mSec */
/* completion) */
/* H_LongBusyOrder10mSec: Try again (hint: may be up to */
/* 10mSec completion) */
hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partner */
/* Vterm IOAs */
uint64 unit-address /* As specified in the Virtual IOA’s device tree node */
);]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: Virtual IOA&#8217;s unit address, as specified in
the IOA&#8217;s device tree node.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Validate that the unit address belongs to the partition and to a
server Vterm IOA and that there exists a valid connection between this
server Vterm IOA and a partner, else H_Parameter.</para>
</listitem>
<listitem>
<para>Break the connection between the server Vterm IOA specified by
the unit address and the client Vterm IOA, preventing further
H_PUT_TERM_CHAR and H_GET_TERM_CHAR operations between the two Vterm IOAs
(until a future successful H_REGISTER_VTERM operation), and return
H_Success.</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Implementation Note:</emphasis> If the hypervisor returns an
H_Busy, H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, software must
call H_FREE_VTERM again with the same parameters. Software may choose to
treat H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy.
The hypervisor, prior to returning H_Busy, H_LongBusyOrder1mSec, or
H_LongBusyOrder10mSec, will have placed the virtual adapter in a state
that will cause it to not accept any new work nor surface any new virtual
interrupts.</para>
<para>&#160;</para>
</simplesect>
</section>
</section>
</section>
</section>
<section xml:id="sec_vterm_multiplex">
<title>Vterm Multiplex</title>
<para>Virtual Serial Multiplex (VSM) IOA allows a highly-privileged logical
partition to serve multiple simultaneous partner partition's client Vterm
IOAs. Management consoles are able to indirectly interact with a single VSM
IOA to access multiple simultaneous partner partition's client virtual serial
sessions up to a maximum number of simultaneous connections.</para>
<para>VSM support is provided by code running in a highly-privileged logical
partition that uses the mechanisms of the Reliable Command/Response Transport
(single sided) and an extended class of Vterm HCALLs to manage, service, and
send virtual serial traffic to platform code.</para>
<para>The VSM architecture is built upon the architecture specified in the
following sections:
<itemizedlist spacing="compact">
<listitem>
<para>
<xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para>
<xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para>
<xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
</para>
<section xml:id="sec_virtual_serial_multiplex_general">
<title>Virtual Serial Multiplex General</title>
<para>This section contains an informative outline of the architectural
intent of use of VSM.</para>
<para>A highly-privileged partition's device tree contains one node notifying
the partition that it has been assigned one VSM adapter. The node's
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis>
and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
properties notify the partition that the virtual adapter is a Virtual Serial
Multiplex adapter. The unit address of the node is used by the partition to
map the virtual device to the OS's corresponding logical representation. The
node's
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
property specifies the interrupt source number that has
been assigned to the VSM for data received on the response queue. The partition,
uses the hcall()s associated with the Reliable Command/Response Transport
facility to register and deregister its CRQ, manage notification of responses,
and send command requests to the platform. A single sided CRQ is implemented
for the VSM adapter. All command requests sent to the platform via H_SEND_CRQ
are processed immediately under the H_SEND_CRQ context.</para>
<section xml:id="sec_vsm_initialization">
<title>VSM Initialization</title>
<para>The device driver, when configured and opened, allocates memory for
its request queue (an array, large enough for all possible outstanding
requests, of 16 byte elements). The driver then pins the queue and maps
it into I/O space, via the kernel’s I/O mapping services that invoke
the H_PUT_TCE hcall(), using the first window pane specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property. The queue is then registered using the H_REG_CRQ hcall().
Finally the device driver registers to receive control when the interrupt
source specified in the virtual IOA’s device tree node signals.</para>
<para>Once the CRQ is setup, the device driver queues an Initialization
Command/Response with the second byte of “Initialize” in order to attempt
to tell the platform side that everything is setup on the partition side.
The response to this send may be that the send has been dropped or has
successfully been sent. If successful, the sender should expect back an
Initialization Command/Response with a second byte of
“Initialization Complete,” at which time the communication path can be
deemed to be open. If dropped, then the sender waits for the receipt
of an Initialization Command/Response with a second byte of “Initialize,”
at which time an “Initialization Complete” message is sent, and if that
message is sent successfully, then the communication path can be deemed
to be open.</para>
<para>The device driver then queues a Version Exchange message to
handshake with the platform and determine any version compatibility.
If successful, the sender should expect back an Version Exchange Response.</para>
<para>
This architecture does not specify the payload format of the requests or
responses. However, the architectural intent is supplied in the following
tables for reference.</para>
<table frame="all" pgwide="1" xml:id="table_crq_message_protocols_vsm_ioa">
<title>CRQ Message Protocols (Virtual Serial Multiplex IOA)</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="55*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Subfield Name</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Header</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Contains Element Valid Bit plus Event Type Encodings (see
<xref linkend="dbdoclet.50569348_49382" />).</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry morerows="1">
<para>Payload</para>
</entry>
<entry>
<para>Command/ Transport Event Code</para>
</entry>
<entry>
<para>For Valid Command Response Entries, see
<xref linkend="table_example_reliable_crq_entry_command_byte_definitions_for_vsm" />.
<?linebreak?>For Transport Event Codes see
<xref linkend="dbdoclet.50569348_93265" />.</para>
</entry>
</row>
<row>
<entry>
<para>2-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Format Dependent</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_example_reliable_crq_entry_command_byte_definitions_for_vsm">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>Example Reliable CRQ Entry Command Byte Definitions for VSM</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="40*" align="center" />
<colspec colname="c2" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Command Byte Value</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Version Exchange</para>
</entry>
</row>
<row>
<entry>
<para>0x81</para>
</entry>
<entry>
<para>Version Exchange Response</para>
</entry>
</row>
<row>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Signal VTERM Interrupt</para>
</entry>
</row>
<row>
<entry>
<para>0x82</para>
</entry>
<entry>
<para>Signal VTERM Interrupt Response</para>
</entry>
</row>
<row>
<entry>
<para>0x03</para>
</entry>
<entry>
<para>Error Indication</para>
</entry>
</row>
<row>
<entry>
<para>0x04 - 0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_example_version_exchange_queue_element_for_vsm">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>Example Version Exchange Queue Element for VSM</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Version Exchange (Response: 0x81)</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Version</para>
</entry>
</row>
<row>
<entry>
<para>4-15</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_example_signal_vterm_interrupt_queue_element_for_vsm">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>Example Signal VTERM Interrupt Queue Element for VSM</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Signal Interrupt (Response: 0x82)</para>
</entry>
</row>
<row>
<entry>
<para>2-7</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Console-token</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_example_error_indication_queue_element_for_vsm">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>Example Error Indication Queue Element for VSM</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x03</para>
</entry>
<entry>
<para>Error Indication</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>4-5</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Error Cause. This field contains a value as detailed in
<xref linkend="table_vsm_error_cause" />
showing the cause of the error.</para>
</entry>
</row>
<row>
<entry>
<para>6-7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Internal Error Detail. This field contains details defined
internally to help narrow down the scope of the Error Cause.</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vsm_error_cause">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>Error Cause</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="40*" align="center" />
<colspec colname="c2" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Firmware Problem</para>
</entry>
</row>
<row>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Device Driver Problem</para>
</entry>
</row>
<row>
<entry>
<para>0x03 - 0xFFFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_open_virtual_serial_session_request">
<title>Open Virtual Serial Session Request</title>
<para>Partition receives a request to open the virtual serial session
for a client partner partition's Vterm IOA.</para>
<itemizedlist>
<listitem>
<para>Partition uses the H_OPEN_VTERM_LP hcall with the client partner
partition's LP ID and session ID as parameters.</para>
</listitem>
<listitem>
<para>On successful open, the partition receives a console-token that
represents the handle of the client LP and session.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_receive_char_event">
<title>Receive Char Event</title>
<para>The partition receives an interrupt when a valid command(s) is/are
received on the response queue.</para>
<itemizedlist>
<listitem>
<para>The partition is notified of Vterm receive data for a specific
client partner partition's LP ID and session (console-token handler)
via the response queue.</para>
</listitem>
<listitem>
<para>The partition uses the H_GET_TERM_CHAR_LP hcall() with the token
handler to receive data from the client Vterm IOA.</para>
</listitem>
<listitem>
<para>The partition continues to call H_GET_TERM_CHAR_LP with the token
handler until H_Success is returned with zero count of characters
specified in R4.</para>
</listitem>
<listitem>
<para>The partition replies to notification CRQ message with a “done”
CRQ response w/ the token handler. This essentially behaves like
the H_EOI for the connection represented by the console-token handler.
Race conditions could occur in any situation; therefore, the
partition should again call H_GET_TERM_CHAR_LP w/ the token handler
to verify the queue is empty.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_send_char_event">
<title>Send Char Event</title>
<para>Partition wishes to send a char or string to a specific client
partner partition's LP ID and session (console-token handler).</para>
<itemizedlist>
<listitem>
<para>Partition uses the H_PUT_TERM_CHAR_LP with the unit-address of
the VSM adapter, the token representing the handle of the client LP
and session, the length of the string to transmit, and the string
to send in char0_7 and char8_15.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_close_virtual_serial_session_request">
<title>Close Virtual Serial Session Request</title>
<para>Partition receives a request to close the virtual serial session.</para>
<itemizedlist>
<listitem>
<para>Partition uses the H_CLOSE_VTERM_LP HCALL with console-token
handler as a parameter.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec_vsm_device_drive_close">
<title>VSM Device Driver Close</title>
<itemizedlist>
<listitem>
<para>Partition uses the H_FREE_CRQ hcall().</para>
</listitem>
<listitem>
<para>The platform “closes” any valid virtual serial sessions and
de-registers each.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="sec_virtual_serial_multiplex_requirements">
<title>Virtual Serial Multiplex Requirements</title>
<para>This normative section provides the general requirements for the
support of VSM.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_virtual_serial_multiplex_requirements"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSM option:</emphasis> The
platform must implement the single sided Reliable Command/Response
Transport option as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_virtual_serial_multiplex_requirements"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSM option:</emphasis> The platform
must implement a new class of VTERM hcalls() as defined in
<xref linkend="sec_virtual_serial_multiplex_hcalls" />.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In addition to the firmware primitives, and the structures they define,
the partition’s OS needs to know specific information regarding the
configuration of the virtual IOAs that it has been assigned so that
it can load and configure the correct device driver code. This information
is provided by the Open Firmware device tree node associated with the
virtual IOA (see
<xref linkend="sec_virtual_serial_multiplex_device_tree_node" />).</para>
</section>
<section xml:id="sec_virtual_serial_multiplex_hcalls">
<title>Virtual Serial Multiplex hcalls()</title>
<para>The following hcall()s are used to send data to and get data from
both the client and sever Vterm IOAs.</para>
<section xml:id="sec_open_vterm_lp">
<title>H_OPEN_VTERM_LP</title>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 hcall ( const uint64 H_OPEN_VTERM_LP,
uint64 unit-address,
uint64 partner-session-id,
uint64 partner-partition-id );]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: The unit address of the VSM IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property of the VSM IOA.</para>
</listitem>
<listitem>
<para>partner-session-id: The partner session ID to which to be connected</para>
</listitem>
<listitem>
<para>partner-partition-id: The partition ID to which to be connected.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the unit-address parameter for validity
against the VSM IOA unit address assigned to the partition, else
return H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Parameter if it detects that the virtual
console associated with the partner-session-id and
partner-partition-id pair could not be found or is not valid.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Parameter if it detects that the virtual
console associated with the partner-session-id and
partner-partition-id pair is already active or migrating.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_State if the VSM CRQ has not been
registered successfully.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_State if the VSM has not successfully
completed the version exchange handshake.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Resource if the maximum number of
simultaneous virtual serial sessions has been exceeded.</para>
</listitem>
<listitem>
<para>Hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or
H_LongBusyOrder10mSec, software must call H_OPEN_VTERM_LP
again with the same parameters. Software may choose to treat
H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy</para>
</listitem>
<listitem>
<para>Else, make a multiplex connection between the VSM IOA specified
by unit-address and the partner Vterm IOA specified by the
partner-partition-id and partner-session-id pair, allowing
future H_PUT_TERM_CHAR_LP and H_GET_TERM_CHAR_LP operations to
flow between the two Vterm IOAs, and return H_Success.</para>
</listitem>
<listitem>
<para>Upon return with H_Success register R4 contains the
console-token to be used as a handle for future H_PUT_TERM_CHAR_LP,
H_GET_TERM_CHAR_LP, and H_CLOSE_VTERM_LP operations along with
applicable CRQ messages for the VSM IOA.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="sec_put_term_char_lp">
<title>H_PUT_TERM_CHAR_LP</title>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 hcall ( const uint64 H_PUT_TERM_CHAR_LP,
uint64 unit-address,
uint64 console-token,
uint64 len,
uint64 char0_7,
uint64 char8_15 );]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: The unit address of the VSM IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property of the VSM IOA.</para>
</listitem>
<listitem>
<para>console-token: The console token received from H_OPEN_VTERM_LP
crq response</para>
</listitem>
<listitem>
<para>len: The length of the string to transmit through the virtual
terminal port. Valid values are in the range of 0-16.</para>
</listitem>
<listitem>
<para>char0_7 and char8_15: The string starts in the high order byte
of register R7 and proceeds toward the low order byte in register R8</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the unit-address parameter for validity
against the VSM IOA unit address assigned to the partition,
else return H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Hardware if it detects that the virtual
console terminal connection is not working.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Closed if it detects that the virtual
console associated with the console-token parameter is not
open or not currently valid.</para>
</listitem>
<listitem>
<para>If the length parameter is outside of the values 0-16 the
hypervisor immediately returns H_Parameter with no other action.</para>
</listitem>
<listitem>
<para>If the partition’s virtual console terminal buffer has room
for the entire string, the hypervisor queues the output string and
returns H_Success. Note: There is always room for a zero-length
string (a zero length write can be used to test the virtual console
terminal connection).</para>
</listitem>
<listitem>
<para>If the buffer cannot hold the entire string, no data is
enqueued and the return code is H_Busy.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="sec_get_term_char_lp">
<title>H_GET_TERM_CHAR_LP</title>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 hcall ( const uint64 H_GET_TERM_CHAR_LP,
uint64 unit-address,
uint64 console-token );]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: The unit address of the VSM IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property of the VSM IOA.</para>
</listitem>
<listitem>
<para>console-token: The console token received from H_OPEN_VTERM_LP
crq response</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the unit-address parameter for validity against
the VSM IOA unit address assigned to the partition, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Hardware if it detects that the virtual
console terminal connection is not working.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Closed if it detects that the virtual
console associated with the console-token parameter is not
open or not currently valid.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Success in all other cases, returning
maximum number of characters available in the partition’s virtual
console terminal input buffer (up to 16) -- a len value of 0
indicates that the input buffer is empty.</para>
</listitem>
<listitem>
<para>Upon return with H_Success register R4 contains the number of
bytes (if any) returned in registers R5 and R6.</para>
</listitem>
<listitem>
<para>Upon return with H_Success the return character string starts
in the high order byte of register R5 and proceeds toward the low
order byte in register R6 for the number of characters specified
in R4. The contents of all other byte locations of registers R5
and R6 are undefined.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="sec_close_vterm_lp">
<title>H_CLOSE_VTERM_LP</title>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 hcall ( const uint64 H_CLOSE_VTERM_LP,
uint64 unit-address,
uint64 console-token );]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>unit-address: The unit address of the VSM IOA, from the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property of the VSM IOA.</para>
</listitem>
<listitem>
<para>console-token: The console token received from H_OPEN_VTERM_LP
hcall response</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>Hypervisor checks the unit-address parameter for validity against
the VSM IOA unit address assigned to the partition, else return
H_Parameter.</para>
</listitem>
<listitem>
<para>Hypervisor returns H_Closed if it detects that the virtual
console associated with the console-token parameter is not open
or not currently valid.</para>
</listitem>
<listitem>
<para>Hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or
H_LongBusyOrder10mSec, software must call H_CLOSE_VTERM_LP
again with the same parameters. Software may choose to treat
H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy</para>
</listitem>
<listitem>
<para>Else, break the multiplex connection between the VSM IOA
specified by unit-address and the partner Vterm IOA specified by
the console-token, and return H_Success.</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
</section>
<section xml:id="sec_virtual_serial_multiplex_device_tree_node">
<title>Virtual Serial Multiplex Device Tree Node</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_virtual_serial_multiplex_device_tree_node"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSM option:</emphasis> The platform's
OF device tree must include as a child of the /vdevice node,
one node of type “vty-mserver”.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_virtual_serial_multiplex_device_tree_node"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VSM option:</emphasis> The platform's
vty-mserver OF node must contain properties defined in
<xref linkend="table_properties_vtymserver_node_vsm" />
(other standard I/O adapter properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="table_properties_vtymserver_node_vsm">
<title>Properties of the vty-mserver Node (Virtual Serial Multiplex IOA)</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="left" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="60*" align="left" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the virtual
device name, the value shall be
<literal>&#8220;vty-mserver&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the virtual
device type, the value shall be
<literal>&#8220;serial-multiplex&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the programming
models that are compatible with this virtual IOA, the value shall be
<literal>&#8220;IBM,serial-multiplex&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and
persistent location code associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the
register addresses, used as the unit address (unit
ID), associated with this virtual IOA presented as
an encoded array as with <emphasis role="bold"><literal>encode-phys</literal></emphasis>.
Because this virtual IOA's parent, <literal>/vdevice</literal>, has
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
value of 1 and
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis>
value of 0, the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property value for this device consists of a single cell.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window
associated with this virtual IOA presented as an encoded
array of two sets (two window panes) of three values (LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis> respectively.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual
IOA presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell
containing the interrupt source number, and the
second cell containing the sense code 0 indicating positive
edge triggered. The interrupt source number being the value
returned by the H_XIRR or H_IPOLL hcall().</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this node.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
size format. The property value specifies the number
of cells that are used to encode the size field of
dma-window properties. This property is present when the
dma address size format cannot be derived using
the method described in the definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
format. The property value specifies the number
of cells that are used to encode the physical address field of
dma-window properties. This property is present when the
dma address format cannot be derived using
the method described in the definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
</section>
<section xml:id="sec_vmc">
<title>Virtual Management Channel (VMC)</title>
<para>PAPR Virtual Management Channel (VMC) support is provided
by code running in a logical partition that uses the
mechanisms of the Reliable Command/Response Transport and
Logical Remote DMA of the Synchronous VIO Infrastructure
to service and to send requests to platform code. The
purpose of this interface is to communicate platform
management information between designated logical
partition and the platform.</para>
<para>The VMC architecture is built upon the architecture specified in the following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
<section xml:id="sec_vmc_requirement">
<title>Virtual Management Channel Requirements</title>
<para>This normative section provides the general requirements for the support of VMC.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vmc_requirement"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VMC option:</emphasis>The platform must
implement the Reliable Command/Response Transport option
as defined in <xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vmc_requirement"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VMC option:</emphasis>The platform must
implement the Logical Remote DMA option as defined in
<xref linkend="dbdoclet.50569348_61656" />.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In addition to the firmware primitives, and the structures
they define, the partition’s OS needs to know specific information
regarding the configuration of the virtual IOAs that it has been
assigned so that it can load and configure the
correct device driver code. This information is provided by the Open
Firmware device tree node associated with the
virtual IOA (see <xref linkend="sec_vmc_devtree" />).</para>
</section>
<section xml:id="sec_vmc_devtree">
<title>Partition Virtual Management Channel Device Tree Node</title>
<para>Partition VMC IOA nodes have no children nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vmc_devtree"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VMC option:</emphasis> The platform’s
Open Firmware device tree for client partitions must include as
a child of the <emphasis role="bold"><literal>/vdevice</literal></emphasis>
node, a node of type &#8220;vmc&#8221; as the
parent of a sub-tree representing the virtual IOAs
assigned to the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vmc_devtree"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VMC option:</emphasis> The platform’s
<emphasis role="bold"><literal>vmc</literal></emphasis>
Open Firmware node must contain properties as defined in
<xref linkend="table_vmc_node_properties" />
(other standard I/O adapter properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="table_vmc_node_properties">
<title>Properties of the VMC Node in the Client Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="left" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="60*" align="left" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the virtual
device name, the value shall be
<literal>&#8220;ibm,vmc&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the virtual
device type, the value shall be
<literal>&#8220;ibm,vmc&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the programming
models that are compatible with this virtual IOA, the value shall be
<literal>&#8220;IBM,vmc&#8221;</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and
persistent location code associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the
register addresses, used as the unit address (unit
ID), associated with this virtual IOA presented as
an encoded array as with <emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
value shall be 0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property used for unit address no actual locations used, therefore, the size field
has zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window
associated with this virtual IOA presented as an encoded
array of two sets (two window panes) of three values (LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
Of these two triples, the first describes the window
pane used to map server partition (the
designated management partition) memory, the second is the
window pane through which the client partition
(the platform partition) maps its memory that it makes
available to the server partition.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual
IOA presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell
containing the interrupt source number, and the
second cell containing the sense code 0 indicating positive
edge triggered. The interrupt source number being the value
returned by the H_XIRR or H_IPOLL hcall().</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this node.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
size format. The property value specifies the number
of cells that are used to encode the size field of
dma-window properties. This property is present when the
dma address size format cannot be derived using
the method described in the definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
format. The property value specifies the number
of cells that are used to encode the physical address field of
dma-window properties. This property is present when the
dma address format cannot be derived using
the method described in the definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section xml:id="sec_vasi">
<title>Virtual Asynchronous Services Interface (VASI)</title>
<para>The PAPR Virtual Asynchronous Services Interface (VASI)
allows an authorized virtual server partition (VSP) to
safely access the internal state of a specific partition.
The access provided by VASI enables high level administrative
services such as partition migration, hibernation and
virtualization of partition logical real memory. VASI uses the
mechanisms of the Reliable Command/Response Transport a
nd Logical Remote DMA of the Synchronous VIO Infrastructure
to service requests.</para>
<para>VASI is built upon the architecture specified in the following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
<section xml:id="sec_vasi_overview">
<title> VASI Overview</title>
<section xml:id="sec_vasi_streams">
<title>VASI Streams, Services and States</title>
<para>A single VASI virtual IOA may be capable of supporting
multiple streams of operations (up to the number presented in the
<emphasis role="bold"><literal>&#8220;ibm,#vasi-streams&#8221;</literal></emphasis>
property, see
<xref linkend="table_vasi_node_properties" />)
each representing a specific high level operation such as an
individual logical partition migration, or a unique logical
partition hibernation, etc. The hypervisor and the various
logical partitions use the VASI_Stream_ID as a handle to associate
the services that each provide to the specific high level function.
Similarly a single VASI virtual IOA may be
capable of supporting multiple service sessions (opens) for
each VASI_Stream_ID (up to the number negotiated by the
#Opens field of the capabilities string, see
<xref linkend="sec_vasi_exchange_capabilities" />).</para>
<para>VASI streams and individual service sessions may be in
one of several states. Refer to the specific high level function description in
<xref linkend="sec_vasi_op_stream_specs" />
for the state descriptions and transition triggers that are defined for each high level function.</para>
</section>
<section xml:id="sec_vasi_handles">
<title>VASI Handles</title>
<para>VASI defines several versions of handles. The VASI Stream
ID is used to associate the elements of the same high level
function (such as a specific partition migration operation).
In this case, the various partitions are assigned roles and a
VASI Stream ID. By opening a VASI virtual IOA with a given
VASI Stream ID and Service parameter, the partition declares
its intent to perform the specified service for the specific
high level operation. By means outside the scope of
PAPR, the platform is told to expect such service from the
specific partition; thus when the match happens, the high
level operation is enabled. At open time, the platform and
partition negotiate a pair of convenient handles to use as a
substitute for the architecturally opaque VASI Stream ID.
This pair of 4 byte handles are called the TOP/BOTTOM.
The TOP field is used by the partition to denote its
operations for the specific VASI Stream ID, while the BOTTOM
field provides that function for the platform firmware.</para>
<para>The first 8 bytes of a VASI data buffer are reserved for
Virtual Server Partition (VSP) use as the buffer correlator field.
The buffer correlator field is architecturally opaque. The
architectural intent is that the buffer correlator field is a VSP
handle to the data buffer control block.</para>
</section>
<section xml:id="sec_vasi_semantics">
<title>Semantic Conventions</title>
<para>The convention for the specification of VASI CRQ message
processing semantics is via a specifically ordered sequence
of operations. Implementations are not required to code in these
sequences but are required to appear as if they
did. In general, parameters and operational state are first
verified, followed by the operation to be performed if all the
parameter/state checks succeed. If a check fails, a response is
generated at that point and further processing of the message
is abandoned. Note that standard CRQ processing operations
(message enqueue and dequeue processing such as
finding the next valid message, resetting the
valid message bit when processing is complete, etc. (See
<xref linkend="dbdoclet.50569348_48491"/>)
are assumed and not explicitly included in the semantic
specification.</para>
</section>
</section>
<section xml:id="sec_vasi_data_buffers">
<title>VASI Data Buffers (Normative)</title>
<para>Data buffers used by VASI are defined as from ILLAN (See
<xref linkend="dbdoclet.50569350_23147" />).
VASI references data buffers via a valid buffer descriptor (Control
Byte = 0x80) as from ILLAN (See
<xref linkend="dbdoclet.50569350_23147" />).
relative to first pane of the VASI virtual IOA
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. The first 8 bytes of a
data buffer are reserved for an OS opaque handle.
A filled data buffer contains either a VASI Download Request
Specifier or a VASI Operation Request Specifier; refer to
<xref linkend="sec_vasi_download_request" /> or
<xref linkend="sec_vasi_operation_request" />
respectively, following the opaque handle. Buffers are supplied to
the VASI virtual IOA via the VASI Add Buffer CRQ request message,
and returned to the VASI device driver in operation requests such as the VASI
Operation CRQ request message or, for those that have not
been used by operation requests, via responses to the VASI
Free Buffer CRQ request message. Closing a VASI service
session releases buffers queued for that service session in
the VASI virtual IOA, while deregistering the VASI virtual
IOA CRQ does the same for all of the VASI virtual IOA
service sessions.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The platform
must implement the Reliable Command/Response Transport option (See
<xref linkend="dbdoclet.50569348_48491" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The storage
for VASI data buffers to be used by a given VASI virtual IOA
must be TCE mapped within the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property as presented in the device
tree node of the VASI virtual IOA Open Firmware
device tree node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> Firmware must
not modify the first 8 bytes (Buffer Correlator field) of a VASI data buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> Immediately following
the first 8 bytes of a filled VASI data buffer must be either
a VASI Download Request Specifier or a VASI Operation Request Specifier.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The VASI Download
Request Specifier must be formatted as per
<xref linkend="sec_vasi_download_request" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_data_buffers"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The VASI Operation
Request Specifier must be formatted as per
<xref linkend="sec_vasi_operation_request" />.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec_vasi_download_request">
<title>VASI Download Request Specifier</title>
<para>The VASI Download Request Specifier is presented in
<xref linkend="figure_vasi_download_req" />.
The VASI Download Request Specifier is used with the VASI Download Request
message see
<xref linkend="sec_vasi_download" />.</para>
<figure xml:id="figure_vasi_download_req">
<title>VASI Download Request Specifier structure</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/vasi_download_request_specifier.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/vasi_download_request_specifier.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_operation_request">
<title>VASI Operation Request Specifier</title>
<para>The VASI Operation Request Specifier is presented in
<xref linkend="figure_vasi_operation_request_specifier" />.
The TOP/BOTTOM (8 bytes) field is a pair of 4 byte opaque handles
as negotiated by the VASI Open Request/Response pair see
<xref linkend="sec_vasi_open" />. </para>
<orderedlist>
<title>Expected Semantics of VASI operation requests:</title>
<listitem>
<para>Operation length is communicated by the summation of the
lengths of the buffer segment control structures following
the operation correlator field.</para>
</listitem>
<listitem>
<para>Operations that write at the end of the file normally
extend the file. If extending the file is not possible due to resource
constraints, then the operation is aborted at the end of
the file, the VASI operation response message carries
the “End of File” status with the Residual field containing
the number of requested bytes that were not transferred
(Residual value of all ones indicates Residual field overflow).</para>
</listitem>
<listitem>
<para>Read operations that access beyond the end of the file are
aborted at the end of the file. The VASI operation response
message carries the “End of File” status with the Residual
field containing the number of requested bytes
that were not transferred (Residual value of all
ones indicates Residual field overflow).</para>
</listitem>
<listitem>
<para>Sequential writes deliver the input stream of bytes to the
receiver in the same order, but not necessarily in the same
blocking as originated by the sender.</para>
</listitem>
<listitem>
<para>Index operations carry the additional semantic over the
corresponding sequential operation that they are a collection
of one or more sub-operations of the same type (read/write).
Each sub-operation specification starts with a
control field encoding of 0xC0 that carries the 512
byte file block index of the start of the operation. The file cursor
can then be adjusted within the block using a control
field of 0x40 followed by a 3 byte binary offset (legal
values 0-511). This offset allows operations to beginning
on any byte boundary within the specified 512 byte
block index. The remainder of each sub-operation
specification is a scatter gather list. The sub-operation length is
defined by the number of bytes of data/buffer
supplied in the sub-operation scatter gather list.</para>
</listitem>
<listitem>
<para>The “Hardware” status code indicates a failure due to
any hardware problem including physical I/O.</para>
</listitem>
<listitem>
<para>The “Invalid Buffer Correlator” status code is reserved
for failure to find the operation buffer.</para>
</listitem>
<listitem>
<para>The “Invalid VASI Operation Request Specifier” status
code is used for any failure in the decode of the operation
buffer not specifically called out by a previous semantic.</para>
</listitem>
<listitem>
<para>The first control field of a scatter gather list may be a
byte offset encoded with a control field of 0x40 and followed
by a 3 byte binary offset (legal values 0-511). This offset
allows operations to beginning on any byte boundary
within the specified 512 byte block index.</para>
</listitem>
<listitem>
<para>The control field encoding 0xC0 indicates that the original
operation is conjoined with a second indexed operation
of the same direction starting at a new 512 byte block
index (as indicated in the following 7 bytes). The conjoined
index operation has its own scatter gather list optionally
starting with a byte offset, followed by one or more data
buffers.</para>
</listitem>
<listitem>
<para>Operation Modifiers:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>000: Base Operation</para>
</listitem>
<listitem>
<para>001: Server Takeover Warning: informs the targeted
VASI server that another VASI server had previously
hosted the operation stream and that it may need to
perform additional steps to process this request.</para>
</listitem>
<listitem>
<para>010 : 111 Reserved</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
<figure xml:id="figure_vasi_operation_request_specifier">
<title>VASI Operation Request Specifier structure</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/vasi_operation_request_specifier.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/vasi_operation_request_specifier.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
</section>
<section xml:id="sec_vasi_crq_message">
<title>VASI CRQ Message Definition (Normative)</title>
<para>For the VASI interface, all CRQ messages are defined to use the following base format:</para>
<table frame="all" pgwide="1" xml:id="table_vasi_general_crq_element">
<title>General Form of VASI Reliable CRQ Element</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Header</para>
</entry>
<entry>
<para>Contains Element Valid Bit plus Event Type Encodings (
<xref linkend="dbdoclet.50569348_49382" />).</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Format/Transport Event Code</para>
</entry>
<entry>
<para>For Valid Command Response Entries, see
<xref linkend="table_reliable_crq_entry_format_for_vasi" />.
For Transport Event Codes see
<xref linkend="dbdoclet.50569348_93265" />.</para>
</entry>
</row>
<row>
<entry>
<para>2-15</para>
</entry>
<entry>
<para>Payload</para>
</entry>
<entry>
<para>Format dependent.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<figure xml:id="figure_general_format_crq_element">
<title>General format of a CRQ element</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/general_format_crq_element.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/general_format_crq_element.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_crq_message"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The format byte of VASI
CRQ messages must be as defined in
<xref linkend="table_reliable_crq_entry_format_for_vasi" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="table_reliable_crq_entry_format_for_vasi">
<?dbhtml table-width="70%" ?><?dbfo table-width="70%" ?>
<title>Reliable CRQ Entry Format Byte Definitions for VASI (Header=0x80)</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Format Byte Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>VASI Capabilities Request</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>VASI Open Request</para>
</entry>
</row>
<row>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>VASI Close Request</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>VASI Add Buffer Request</para>
</entry>
</row>
<row>
<entry>
<para>0x5</para>
</entry>
<entry>
<para>VASI Free Buffer Request</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>VASI Download Request</para>
</entry>
</row>
<row>
<entry>
<para>0x07</para>
</entry>
<entry>
<para>VASI Operation Request</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry>
<para>VASI Signal Request</para>
</entry>
</row>
<row>
<entry>
<para>0x9</para>
</entry>
<entry>
<para>VASI State Request</para>
</entry>
</row>
<row>
<entry>
<para>0x0A-0x0F</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x10</para>
</entry>
<entry>
<para>VASI Progress Request</para>
</entry>
</row>
<row>
<entry>
<para>0x11</para>
</entry>
<entry>
<para>VASI Add Buffer Indirect Request</para>
</entry>
</row>
<row>
<entry>
<para>0x12</para>
</entry>
<entry>
<para>VASI Message Upload</para>
</entry>
</row>
<row>
<entry>
<para>0x13</para>
</entry>
<entry>
<para>VASI Message Download</para>
</entry>
</row>
<row>
<entry>
<para>0x14-0x80</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x81</para>
</entry>
<entry>
<para>VASI Capabilities Response</para>
</entry>
</row>
<row>
<entry>
<para>0x82</para>
</entry>
<entry>
<para>VASI Open Response</para>
</entry>
</row>
<row>
<entry>
<para>0x83</para>
</entry>
<entry>
<para>VASI Close Response</para>
</entry>
</row>
<row>
<entry>
<para>0x84</para>
</entry>
<entry>
<para>VASI Add Buffer Response</para>
</entry>
</row>
<row>
<entry>
<para>0x85</para>
</entry>
<entry>
<para>VASI Free Buffer Response</para>
</entry>
</row>
<row>
<entry>
<para>0x86</para>
</entry>
<entry>
<para>VASI Download Response</para>
</entry>
</row>
<row>
<entry>
<para>0x87</para>
</entry>
<entry>
<para>VASI Operation Response</para>
</entry>
</row>
<row>
<entry>
<para>0x88</para>
</entry>
<entry>
<para>VASI Signal Response</para>
</entry>
</row>
<row>
<entry>
<para>0x89-0x8F</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x90</para>
</entry>
<entry>
<para>VASI Progress Response</para>
</entry>
</row>
<row>
<entry>
<para>0x91</para>
</entry>
<entry>
<para>VASI Add Buffer Indirect Response</para>
</entry>
</row>
<row>
<entry>
<para>0x92</para>
</entry>
<entry>
<para>VASI Message Upload Response</para>
</entry>
</row>
<row>
<entry>
<para>0x90</para>
</entry>
<entry>
<para>VASI Message Download Response</para>
</entry>
</row>
<row>
<entry>
<para>0x94-0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_crq_message"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis> The status byte
of VASI CRQ response messages must be as defined in
able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
<xref linkend="table_vasi_reliable_crq_response_status" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="table_vasi_reliable_crq_response_status">
<title>VASI Reliable CRQ Response Status Values</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="75*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Format Byte Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Success</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Hardware Error</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Invalid Stream ID</para>
</entry>
</row>
<row>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>Stream ID Abort</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>Invalid Buffer Descriptor: Either the IOBA is too large for
the LIOBN or its logical TCE does not contain a valid
logical address mapping.</para>
</entry>
</row>
<row>
<entry>
<para>0x5</para>
</entry>
<entry>
<para>Invalid buffer length: Either the buffer is less than the
minimum useful buffer size or it does not match one of the first
<emphasis role="bold"><literal>&#8220;ibm,#buffer-pools&#8221;</literal></emphasis>
sizes that were added.</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>Empty: The request could not be satisfied because the
buffer pool was empty</para>
</entry>
</row>
<row>
<entry>
<para>0x7</para>
</entry>
<entry>
<para>Invalid VASI Download Request Specifier</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry>
<para>Invalid VASI Download data: The download data format is invalid.</para>
</entry>
</row>
<row>
<entry>
<para>0x9</para>
</entry>
<entry>
<para>Invalid Buffer Correlator: Does not correspond to an
outstanding data buffer.</para>
</entry>
</row>
<row>
<entry>
<para>0x0A</para>
</entry>
<entry>
<para>Invalid VASI Operation Request Specifier</para>
</entry>
</row>
<row>
<entry>
<para>0x0B</para>
</entry>
<entry>
<para>Invalid Service Specifier</para>
</entry>
</row>
<row>
<entry>
<para>0x0C</para>
</entry>
<entry>
<para>Too many opens</para>
</entry>
</row>
<row>
<entry>
<para>0x0D</para>
</entry>
<entry>
<para>Invalid BOTTOM</para>
</entry>
</row>
<row>
<entry>
<para>0x0E</para>
</entry>
<entry>
<para>Invalid TOP</para>
</entry>
</row>
<row>
<entry>
<para>0x0F</para>
</entry>
<entry>
<para>End of File</para>
</entry>
</row>
<row>
<entry>
<para>0x10</para>
</entry>
<entry>
<para>Invalid Format</para>
</entry>
</row>
<row>
<entry>
<para>0x11</para>
</entry>
<entry>
<para>Unknown Reserved Value</para>
</entry>
</row>
<row>
<entry>
<para>0x12</para>
</entry>
<entry>
<para>Invalid State Transition</para>
</entry>
</row>
<row>
<entry>
<para>0x13</para>
</entry>
<entry>
<para>Race Lost</para>
</entry>
</row>
<row>
<entry>
<para>0x14</para>
</entry>
<entry>
<para>Invalid Signal Code</para>
</entry>
</row>
<row>
<entry>
<para>0x15</para>
</entry>
<entry>
<para>Invalid Indirect Buffer Descriptor: Either the IOBA is too
large for the LIOBN or its logical TCE does not contain a valid
logical address mapping.</para>
</entry>
</row>
<row>
<entry>
<para>0x16</para>
</entry>
<entry>
<para>Invalid Indirect Buffer Length: The indirect buffer size is
not large enough to contain the total number of buffers indicated.</para>
</entry>
</row>
<row>
<entry>
<para>0x17</para>
</entry>
<entry>
<para>Invalid Control Code</para>
</entry>
</row>
<row>
<entry>
<para>0x18</para>
</entry>
<entry>
<para>Invalid Sub-control Code</para>
</entry>
</row>
<row>
<entry>
<para>0x19-0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vasi_req_resp">
<title>VASI Request/Response Pairs</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must validate the format byte in all VASI messages that it receives.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must initiate the processing of VASI messages in the order received
on a given CRQ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
If the format byte value of a received VASI message, as specified in
<xref linkend="table_reliable_crq_entry_format_for_vasi" />,
is “Unused”, “Reserved”, “VASI Operation Request”, or a response other
than “VASI Operation Response”, the platform must declare the format byte invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
If the format byte value is invalid, then the platform must generate a response
message on the corresponding CRQ by copying the received
message with the high order format byte bit set
to a one and the status byte with the “Invalid Format”
status code, and discard the received CRQ message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must fill in all reserved fields in VASI messages that it generates with zeros.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must check that all reserved fields in a VASI message, except the
for the Capability String of the VASI Exchange Capabilities message, that it receives are filled with zeros,
else return the corresponding VASI reply message with a status of “Unknown Reserved Value”.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Exchange Capabilities message must be as defined in
<xref linkend="figure_format_vasi_exchange_cap_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Open message must be as defined in
<xref linkend="figure_format_vasi_open_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Open Request message per the semantics described in
<xref linkend="sec_vasi_open" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Close message must be as defined in
<xref linkend="figure_format_vasi_close_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Close Request message per the semantics described in
<xref linkend="sec_vasi_close" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Add Buffer message must be as defined in
<xref linkend="figure_format_vasi_add_buffer_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Add Buffer Request message per the semantics described in
<xref linkend="sec_vasi_add_buffer" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Free Buffer message must be as defined in
<xref linkend="figure_format_vasi_free_buffer_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Free Buffer Request message per the semantics described in
<xref linkend="sec_vasi_free_buffer" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Download Request message per the semantics described in
<xref linkend="sec_vasi_download" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Download message must be as defined in
<xref linkend="figure_format_vasi_download_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Operation Response message per the semantics described in
<xref linkend="sec_vasi_operation" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Operation message must be as defined in
<xref linkend="figure_format_vasi_operation_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI State Request message per the semantics described in
<xref linkend="sec_vasi_state" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-21.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI State message must be as defined in
<xref linkend="figure_format_vasi_state_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-22.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Progress Request message per the semantics described in
<xref linkend="sec_vasi_progress" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-23.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Progress message must be as defined in
<xref linkend="figure_format_vasi_progress_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-24.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Signal Request message per the semantics described in
<xref linkend="sec_vasi_signal" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-25.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Signal message must be as defined in
<xref linkend="figure_format_vasi_signal_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-26.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
To avoid a return code of “Invalid TOP” or “Invalid BOTTOM”; the VASI
messages: VASI Progress, VASI Add Buffer, VASI Free Buffer, VASI Download, VASI Operation, VASI Signal
and VASI State requests must only be sent after successful VASI Opens and prior to a VASI Close.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-27.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
For the VASI option: The VASI Add Buffer Indirect message must be as defined in
<xref linkend="figure_format_of_the_vasi_add_buffer_indirect_crq_elem" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-28.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Add Buffer Indirect Request message
per the semantics described in
<xref linkend="sec_vasi_add_buffer_indirect" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-29.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Message Upload message must be as defined in
<xref linkend="figure_format_of_the_vasi_message_upload_crq_elements" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-30.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Message Upload Request message
per the semantics described in
<xref linkend="sec_vasi_message_upload" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-31.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The VASI Message Download message must be as defined in
<xref linkend="figure_format_of_the_vasi_message_download_crq_elements" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_req_resp"
xrefstyle="select: labelnumber nopage"/>-32.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must process the VASI Message Download Request
message per the semantics described in
<xref linkend="sec_vasi_message_download" />.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec_vasi_exchange_capabilities">
<title>VASI Exchange Capabilities</title>
<para>The VASI Exchange Capabilities command response pair is used to negotiate run time characteristics of the VASI virtual
IOA. The using partition issues one VASI Exchange Capabilities request message for each service that it plans to
support, filling in the Capability String field of the exchange capabilities request (see
<xref linkend="table_vasi_capability_string_fields" />)
with the values that it plans to use for that service and enqueues the request. The VASI virtual
IOA copies to the response Capability String, the values from the request capability string that it can support. The Capability
string boolean fields are defined such that zero indicates that the characteristic is not supported. Capability
string fields that represent numeric values may be reduced by the VASI virtual IOA from the requested value to the
supported value with the numeric value zero being possible.</para>
<para>Status Values defined for the VASI Exchange Capabilities response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_exchange_cap_crq_elem">
<title>Format of the VASI Exchange Capabilities CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_exchange_cap_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_exchange_cap_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<table frame="all" pgwide="1" xml:id="table_vasi_capability_string_fields">
<title>Capability String Fields</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="left" />
<colspec colname="c2" colwidth="30*" align="left" />
<colspec colname="c3" colwidth="50*" align="left" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Location (Byte:Bit - Byte:Bit)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Service</para>
</entry>
<entry>
<para>3:0 - 3:7</para>
</entry>
<entry>
<para>Supported Services code see <xref linkend="sec_vasi_op_stream_specs" /></para>
</entry>
</row>
<row>
<entry namest="c1" nameend="c3">
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Reserved 1</para>
</entry>
<entry>
<para>4:1 - 12:7</para>
</entry>
<entry>
<para>Reserved for future expansion</para>
</entry>
</row>
<row>
<entry namest="c1" nameend="c3">
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>MSP Failover</para>
</entry>
<entry>
<para>13:0</para>
</entry>
<entry>
<para>MSP failover supported</para>
</entry>
</row>
<row>
<entry>
<para>Multiple opens</para>
</entry>
<entry>
<para>13:1</para>
</entry>
<entry>
<para>Multiple opens per stream supported</para>
</entry>
</row>
<row>
<entry>
<para>Buffer Management Scheme 2</para>
</entry>
<entry>
<para>13:2</para>
</entry>
<entry>
<para>Hypervisor's support of buffer mangement scheme version 2</para>
</entry>
</row>
<row>
<entry>
<para>Enhanced VASI Signal to Suspend</para>
</entry>
<entry>
<para>13:3</para>
</entry>
<entry>
<para>VASI Signal to Suspend to be sent when the management console indicates the client is suspendable</para>
</entry>
</row>
<row>
<entry>
<para>Enhanced Progress CRQ</para>
</entry>
<entry>
<para>13:4</para>
</entry>
<entry>
<para>Progress CRQ includes a correlator</para>
</entry>
</row>
<row>
<entry>
<para>Add Buffer Indirect Command</para>
</entry>
<entry>
<para>13:5</para>
</entry>
<entry>
<para>Add Buffer Indirect command supported</para>
</entry>
</row>
<row>
<entry>
<para>Supported Download Forms</para>
</entry>
<entry>
<para>13:6 Immediate <?linebreak?>
13:7 Indirect</para>
</entry>
<entry>
<para>The forms of VASI Download that are supported. This is a bit
field so any combination is possible to represent. Immediate
and indirect refer to the buffer placement, either directly
following in the operation specifier or at a location specified by
an address.</para>
</entry>
</row>
<row>
<entry>
<para>Supported Operations</para>
</entry>
<entry>
<para>14:0 Read Squential Immediate <?linebreak?>
14:1 Read Sequential Indirect<?linebreak?>
14:2 Read Indexed Immediate<?linebreak?>
14:3 Read Indexed Indirect<?linebreak?>
14:4 Write Sequential Immediate<?linebreak?>
14:5 Write Sequential Indirect<?linebreak?>
14:6 Write Indexed Immediate<?linebreak?>
14:7 Write Indexed Indirect </para>
</entry>
<entry>
<para>The forms of VASI Operations that are supported. This is a bit
field so any combination is possible to represent. Sequential
and indexed refer to the starting point of the operation
(following the last operation or at a specific block offset).
Immediate and indirect refer to the buffer placement, either
directly following in the operation specifier or at a location
specified by an address.</para>
</entry>
</row>
<row>
<entry>
<para>#Opens</para>
</entry>
<entry>
<para>15:0 - 15-7</para>
</entry>
<entry>
<para>Number of opens (unique TOP/BOTTOM pairs) per VASI
stream that are supported on this VASI Virtual IOA. Valid
values (1-255)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vasi_open">
<title>VASI Open</title>
<para>The VASI Open Command message, see
<xref linkend="figure_format_vasi_open_crq_elem" />,
indicates to the hypervisor that the originator VASI device driver is prepared to provide
the indicated processing service (role) for the indicated VASI stream.</para>
<para>The VASI Open Response message indicates to the originating VASI device driver that the hypervisor is prepared to
proceed with the indicated VASI stream.</para>
<para>Status Values defined for the VASI Open response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid Stream ID: The Stream ID parameter is not currently valid for this VASI virtual device.</para>
</listitem>
<listitem>
<para>Stream ID Aborted</para>
</listitem>
<listitem>
<para>Too many opens</para>
</listitem>
<listitem>
<para>Invalid Service Specifier: Either reserved value or service not defined for this VASI stream.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Open Request Message:</title>
<listitem>
<para>Construct VASI Open Response message prototype (Including service parameter from request).</para>
</listitem>
<listitem>
<para>Copy low order 8 bytes from Request message to response prototype.</para>
</listitem>
<listitem>
<para>Verify that the Stream ID parameter of the VASI Open Request message is valid for the caller, else respond with the
status of “Invalid Stream ID”.</para>
</listitem>
<listitem>
<para>Verify that the Service parameter of the VASI Open Request message is valid for the caller plus Stream ID pair, else
respond with the status of “Invalid Service Specifier”. Note that the valid “Service” values vary with the specific
high level function being performed (see
<xref linkend="sec_vasi_op_stream_specs" />)
and the role assigned to the calling partition by mechanisms outside of the scope of PAPR.</para>
</listitem>
<listitem>
<para>If the state of the VASI stream specified by the Stream ID of a VASI Open Request message is “Aborted”, respond
with the status value of “Stream ID Aborted”.</para>
</listitem>
<listitem>
<para>If the maximum number of opens has not been reached, then allocate control structures to maintain the state of this
open instance and associate them with a unique BOTTOM parameter -- copy BOTTOM parameter to response message;
else respond with “Too many opens”.</para>
</listitem>
<listitem>
<para>Record the associated TOP parameter value for use in subsequent VASI response and operation request messages.</para>
</listitem>
<listitem>
<para>Respond with Success.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_open_crq_elem">
<title>Format of the VASI Open CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_open_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_open_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_close">
<title>VASI Close</title>
<para>The VASI Close Command message, see
<xref linkend="figure_format_vasi_close_crq_elem" />,
requests the receiver to close the indicated BOTTOM instance of the VASI stream.
Note, other BOTTOM instances remain open.</para>
<para>The VASI Close Response message indicates that the VASI Close command receiver has processed the associated
VASI Close Command message and all previously enqueued messages to the BOTTOM instance. No further CRQ
messages will be enqueued by the closed BOTTOM service, and all enqueued buffers are forgotten.</para>
<para>Status Values defined for the VASI Close response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Close Request Message:</title>
<listitem>
<para>Construct VASI Close Response message prototype (copy low order 14 bytes from request message).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM parameter is valid for caller, else respond “invalid BOTTOM”</para>
</listitem>
<listitem>
<para>Transition the service for the specified VASI stream instance to the “Closed” state -- This process ends after all previously
initiated VASI request messages for the BOTTOM instance have completed.</para>
</listitem>
<listitem>
<para>Insert the TOP recorded at open time for the specified BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Free queued buffers and deallocate the control structures associated with the BOTTOM parameter, then respond
Success.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_close_crq_elem">
<title>Format of the VASI Close CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_close_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_close_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_add_buffer">
<title>VASI Add Buffer</title>
<para>The VASI Add Buffer Command message, see
<xref linkend="figure_format_vasi_add_buffer_crq_elem" />,
indicates to the hypervisor that the originator VSP device driver is providing the hypervisor with an empty
buffer for the specific BOTTOM instance.</para>
<para>The hypervisor organizes its input buffers into N buffer pools per service, by size as indicated by the buffer descriptor.
The VASI
<emphasis role="bold"><literal>&#8220;ibm,#buffer-pools&#8221;</literal></emphasis>
device tree property relates how many buffer size pools the firmware implements.
The first N different sizes supplied by the device driver specifies the sizes of the N buffer size pools -- buffers of
other sizes are rejected.</para>
<para>The VASI Add Buffer Response message indicates to the originating VASI device driver that the hypervisor has processed
the associated VASI Add Buffer Command message. All VASI Add Buffer CRQ messages generate a VASI
Add Buffer Response message to provide feedback to the VASI device driver for flow control of the firmware's VASI
CRQ.</para>
<para>The successful Add Buffer Response CRQ message indicates the buffer size of the pool upon which the buffer was enqueued,
and the number of free buffers on the indicated buffer size pool after the add (to indicate buffer utilization).</para>
<para>Status Values defined for the VASI Add Buffer response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Buffer Descriptor</para>
</listitem>
<listitem>
<para>Invalid Buffer Length</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Add Buffer Request Message:</title>
<listitem>
<para>Construct VASI Add Buffer Response message prototype (copy low order 14 bytes from the request message to the
response prototype).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM field, else respond “Invalid BOTTOM”.</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Validate high order Buffer Descriptor bit is 0b1, else respond with “Invalid Buffer Descriptor”</para>
</listitem>
<listitem>
<para>Validate that the Buffer Descriptor address translates through the LIOBN of the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property, else respond with “Invalid Buffer Descriptor”.</para>
</listitem>
<listitem>
<para>Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype.</para>
</listitem>
<listitem>
<para>If the Buffer Descriptor length field does not match the buffer length of one of the buffer pools then:
<itemizedlist>
<listitem>
<para>If buffer lengths are assigned to all buffer pools, then respond with “Invalid Buffer Length”</para>
</listitem>
<listitem>
<para>Else select an unassigned buffer pool, and assign its length to match the length field of the Buffer Descriptor.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Enqueue the buffer descriptor onto the per service session (“BOTTOM”) pool whose buffer length matches the
length field of the Buffer Descriptor, increment the Free Buffers in Pool count for the pool; inserting the result into
the response prototype along with the buffer size, clear the reserved fields and respond with “Success”</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_add_buffer_crq_elem">
<title>Format of the VASI Add Buffer CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_add_buffer_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_add_buffer_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_free_buffer">
<title>VASI Free Buffer</title>
<para>The VASI Free Buffer Command message, see
<xref linkend="figure_format_vasi_free_buffer_crq_elem" />
requests the hypervisor to return an empty data buffer of the specified size to the originator VSP device
driver. This call is used to recover buffers. It may be used to recover buffers at the completion of a VASI operation
stream. All buffers added to a VASI virtual IOA service session (“BOTTOM”) are forgotten by the virtual IOA when
the service session is closed or the IOA’s CRQ is deregistered.</para>
<para>The VASI Free Buffer Response message indicates to the originating VASI device driver that the hypervisor has processed
the associated VASI Free Buffer Command message. All VASI Free Buffer CRQ messages generate a VASI
Free Buffer Response message. If the Status field of the VASI Free Buffer Response CRQ message is “Success” then
the last 8 bytes contain the Buffer Correlator (first 8 bytes of the data buffer) of the selected empty data buffer. The last
8 bytes of the VASI Free Buffer Response CRQ message are undefined for any non “Success” Status value.</para>
<para>Status Values defined for the VASI Free Buffer response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Buffer Length</para>
</listitem>
<listitem>
<para>Empty</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Free Buffer Request Message:</title>
<listitem>
<para>Construct VASI Free Buffer Response message prototype with the Buffer Correlator field zero.</para>
</listitem>
<listitem>
<para>Validate the BOTTOM field, else respond “Invalid BOTTOM”.</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>If the request message Buffer Length field does not match one of the pool lengths, then respond “Invalid Buffer
Length”.</para>
</listitem>
<listitem>
<para>If the buffer pool associated with the Buffer Length field is empty, then respond “Empty”.</para>
</listitem>
<listitem>
<para>Dequeue a Buffer Descriptor from the buffer pool associated with the Buffer Length field.</para>
</listitem>
<listitem>
<para>Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype
and respond “Success”.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_free_buffer_crq_elem">
<title>Format of the VASI Free Buffer CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_free_buffer_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_free_buffer_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_download">
<title>VASI Download</title>
<para>The VASI Download Command message, see
<xref linkend="figure_format_vasi_download_crq_elem" />
requests the hypervisor to process the VASI Download data buffer specified by the
originator VSP device driver.</para>
<para>The VASI Download Response message indicates to the originating VSP that the hypervisor has processed the associated
VASI Download Command message. Unless the Status field of the VASI Download Response CRQ message is
“Invalid Buffer Descriptor”, the last 8 bytes contain the Buffer Correlator (first 8 bytes of the data buffer) of the data
buffer specified by the Buffer Descriptor field of the VASI Download Command CRQ message. The last 8 bytes of the
VASI Download Response CRQ message are undefined for the “Invalid Buffer Descriptor” Status value.</para>
<para>Status Values defined for the VASI Download response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Buffer Descriptor</para>
</listitem>
<listitem>
<para>Invalid VASI Download Request Specifier</para>
</listitem>
<listitem>
<para>Invalid VASI Download data</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Download Request Message:</title>
<listitem>
<para>Construct VASI Download Response message prototype (copy low order 14 bytes from Request message to response
prototype).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM field, else respond “Invalid BOTTOM”.</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Validate high order Buffer Descriptor bit is 0b1, else respond with “Invalid Buffer Descriptor”</para>
</listitem>
<listitem>
<para>Validate that the Buffer Descriptor address translates through the LIOBN of the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property, else respond with “Invalid Buffer Descriptor”.</para>
</listitem>
<listitem>
<para>Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype.</para>
</listitem>
<listitem>
<para>Verify that the BOTTOM parameter of the buffer’s VASI Download Request Specifier is valid for the caller and the
Download service for the associated Stream ID is Open by the caller, else respond with “Invalid VASI Download
Request Specifier”.</para>
</listitem>
<listitem>
<para>The Download service processes the buffer data; if an error is detected in the buffer data respond with “Invalid VASI
Download data”, else respond with “Success”.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_download_crq_elem">
<title>Format of the VASI Download CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_download_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_download_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_operation">
<title>VASI Operation</title>
<para>The VASI Operation Request message, see Figure 47‚ “Format of the VASI Operation CRQ elements‚” on page 731,
requests the receiving VSP to process the VASI Operation specified in the data buffer indicated by the Buffer Correlator
field. The Buffer Correlator field is copied from the first 8 bytes of the data buffer as supplied by the VSP using the
VASI add buffer request. VASI Operation Requests are used to upload data on migration/hibernation (Write Sequential)
and for VPM paging requests (using indexed Read/Write).</para>
<para>The VASI Operation Response message indicates to the hypervisor that the VSP has processed the associated VASI
Operation Command message. Unless the Status field of the VASI Operation Response CRQ message is “Invalid
Buffer Correlator”, the last 8 bytes contain the Operation Correlator (fourth 8 bytes of the data buffer) of the data buffer
that the hypervisor selected for this operation. The last 8 bytes of the VASI Operation Response CRQ message are undefined
for the “Invalid Buffer Correlator” Status value. The VSP validates that the TOP parameter corresponds to an
open instance against a VASI stream ID, else it responds “Invalid TOP”. Similarly the VSP validates the format of the
remainder of the buffer, else responds “Invalid VASI Operation Request Specifier”.</para>
<para>Status Values defined for the VASI Operation response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid Buffer Correlator</para>
</listitem>
<listitem>
<para>Invalid TOP</para>
</listitem>
<listitem>
<para>Invalid VASI Operation Request Specifier</para>
</listitem>
<listitem>
<para>Stream ID Aborted</para>
</listitem>
<listitem>
<para>End of File</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Operation Response Message:</title>
<listitem>
<para>Verify that the Operation Correlator references a valid outstanding VASI Operation, else discard message.<?linebreak?>
NOTE: while an invalid operation correlator is a very serious error there is no obvious instance to which to deliver the
error.</para>
</listitem>
<listitem>
<para>Mark the operation control block as referenced by the Operation Correlator with the Status and Residual values, refer
to <xref linkend="sec_vasi_operation_request" />, from the Response message and mark the
response message as being processed.</para>
</listitem>
<listitem>
<para>Further processing of the operation control block is covered in the specification for the specific VASI Operation
Stream. See <xref linkend="sec_vasi_op_stream_specs" />.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_operation_crq_elem">
<title>Format of the VASI Operation CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_operation_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_operation_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_signal">
<title>VASI Signal</title>
<para>The VASI Signal Command message (See
<xref linkend="figure_format_vasi_signal_crq_elem" />)
informs the VASI Virtual IOA of the VASI Stream, associated with the BOTTOM parameter, of the condition specified
by the “Signal Code” parameter; optionally, a non-zero reason code may be associated with the event so that firmware
may record the event using facilities and methods that are outside the scope of this architecture.</para>
<para>The valid signal codes, and reason codes are unique to the specific VASI operation stream. See
<xref linkend="table_vasi_signal_codes" /> and
<xref linkend="sec_vasi_op_stream_specs" />
respectively for more details.</para>
<para>Status Values defined for the VASI State response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Signal Code</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for processing the VASI Signal Request Message:</title>
<listitem>
<para>Construct VASI Signal Response message prototype (copy the low order 14 bytes from the Request message to the
response prototype).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM parameter for the caller; else respond “Invalid BOTTOM”</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Determine the VASI stream associated with the BOTTOM parameter.</para>
</listitem>
<listitem>
<para>If the “Signal” parameter represents an invalid signal
code for the VASI operation stream represented by the BOTTOM parameter (refer to
<xref linkend="table_vasi_signal_codes" />),
then respond “Invalid Signal Code”.</para>
</listitem>
<listitem>
<para>Initiate the VASI stream event processing for the VASI operation
stream represented by the BOTTOM parameter as defined under
<xref linkend="sec_vasi_op_stream_specs" />
for the current state and the condition represented by the “Signal”
parameter, record the value of the “Reason” parameter, and respond “Success”.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_signal_crq_elem">
<title>Format of the VASI Signal CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_signal_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_signal_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_state">
<title>VASI State</title>
<para>The VASI virtual IOA generates a VASI State Request message, see
<xref linkend="figure_format_vasi_state_crq_elem" />,
to each VASI open session instance (TOP), that is associated (through a VASI Open) with the
VASI Stream ID, each time the VASI stream changes state. Such state change request messages may include an optional
non-zero reason code.</para>
<para>No VASI State Response message is defined. The VASI State Request message is informational, and the receiver does
not generate a response.</para>
<para>The valid states, state transitions, and reason codes are unique to the specific VASI operation stream, see
<xref linkend="sec_vasi_op_stream_specs" />.</para>
<itemizedlist>
<title>Semantics for VASI State Request Message sent only after all other VASI stream state transition processing completes:</title>
<listitem>
<para>For each TOP opened for the VASI stream that changed state.
<itemizedlist>
<listitem>
<para>Construct VASI State Request message prototype.</para>
</listitem>
<listitem>
<para>Fill in the TOP from the values recorded at VASI open time.</para>
</listitem>
<listitem>
<para>Fill in the “Reason” and “To” fields per the completed transition.</para>
</listitem>
<listitem>
<para>Enqueue the request message to the CRQ used to open the associated TOP.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Mark the VASI stream state transition complete.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_state_crq_elem">
<title>Format of the VASI State CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_state_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_state_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_progress">
<title>VASI Progress</title>
<para>The VASI Progress Command message, see
<xref linkend="figure_format_vasi_progress_crq_elem" />,
is applicable to Migration and Hibernation high level operations. It requests the hypervisor to report the number of bytes
of partition state that need to be processed for the VASI migration/hibernation stream associated with the “BOTTOM”
parameter. If this request is made prior to any state transfer requests, it represents the total size of the partition state
data.</para>
<para>If the Status field of the VASI Progress Response CRQ message is “Invalid BOTTOM”, the last 8 bytes of the VASI
Progress Response CRQ message are copied from the corresponding VASI Progress Request message in all cases.</para>
<para>Status Values defined for the VASI State response message:</para>
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Service Specifier</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Semantics for VASI Progress Request Message:</title>
<listitem>
<para>Construct VASI Progress Response message prototype (copy the low order 14 bytes from Request message to response
prototype).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM parameter for the caller, else respond “invalid BOTTOM”</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Validate that the operation stream associated with the BOTTOM parameter is either a migration or a hibernation;
else respond “Invalid Service Specifier”.</para>
</listitem>
<listitem>
<para>Estimate the number of bytes left to transfer (this is best effort since the number may constantly change) placing the
value into the “Number of Bytes Left” field and respond Success.
<itemizedlist>
<listitem>
<para>For the source side of an operation the estimate of the number of bytes left is the number of bytes of dirty status.</para>
</listitem>
<listitem>
<para>For the destination side of an operation the estimate of the number of bytes left is the number of expected status
bytes that the destination knows are not valid (either they were never sent or there has been an indication that they
were subsequently made invalid).</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_vasi_progress_crq_elem">
<title>Format of the VASI Progress CRQ elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_progress_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_progress_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="sec_vasi_add_buffer_indirect">
<title>VASI Add Buffer Indirect</title>
<para>The VASI Add Buffer Indirect Command message, see
<xref linkend="figure_format_of_the_vasi_add_buffer_indirect_crq_elem" />
indicates to the hypervisor that the originator VSP device driver is
providing the hypervisor with multiple empty buffers for the specific BOTTOM
instance.</para>
<para>A maximum of 255 buffers can be sent in a single VASI Add Buffer Indirect
CRQ command, however, the platform may only be able to process a subset of
the buffers in a single call. The buffers do not have to be of the same size.
For each buffer sent, the hypervisor organizes its input buffers into N buffer
pools per service, by size as indicated by the buffer descriptor. The VASI
<emphasis role="bold"><literal>&#8220;ibm,#buffer-pools&#8221;</literal></emphasis>
device tree property relates how many buffer size pools
the firmware implements. The first N different sizes supplied by the device
driver specifies the sizes of the N buffer size pools -- buffers of other
sizes are rejected.</para>
<para>The VASI Add Buffer Indirect Response message indicates to the originating
VASI device driver that the hypervisor has processed the associated VASI Add
Buffer Indirect Command message. All VASI Add Buffer Indirect CRQ messages
generate a VASI Add Buffer Indirect Response message to provide feedback to
the VASI device driver for flow control of the firmware's VASI CRQ.</para>
<para>The count field in the VASI Add Buffer Indirect response indicates how
many buffers PHYP processed successfully. Buffers are always processed in
order from the beginning of the indirect buffer, so any unprocessed buffers
are always at the end. Buffer processing stops if an error is encountered.
Processing of a subset of buffers per call is not considered an error and
the unprocessed buffers will be freed back to the pool by the VSP to be used
in subsequent calls.</para>
<para>If the Status field of the VASI Add Buffer Indirect CRQ message is
“Invalid Indirect Buffer Descriptor” then the last 8 bytes of the response
contains the Indirect Buffer Descriptor, otherwise, the last 8 bytes contain
the CRQ message Correlator (1st 8 Bytes of Indirect Buffer as set by VSP).</para>
<para>If any error is encountered in processing a VASI Add Buffer Indirect
command, the associated VASI stream is transitioned the to the “Aborted”
state by the VSP to terminate the operation and free the stream's buffer pool.</para>
<para>Status Values defined for the VASI Add Buffer Indirect response message:
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Indirect Buffer Descriptor</para>
</listitem>
<listitem>
<para>Invalid Indirect Buffer Length</para>
</listitem>
<listitem>
<para>Invalid Buffer Descriptor</para>
</listitem>
<listitem>
<para>Invalid Buffer Length</para>
</listitem>
</itemizedlist>
</para>
<simplesect>
<title>Semantics for VASI Add Buffer Indirect Request Message:</title>
<itemizedlist>
<listitem>
<para>Construct VASI Add Buffer Indirect Response message prototype
(copy low order 14 bytes from the request message to the response prototype.</para>
</listitem>
<listitem>
<para>Set the Count field (Byte 3) in the response prototype to zero.</para>
</listitem>
<listitem>
<para>Validate the BOTTOM field, else respond “Invalid BOTTOM”.</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response
prototype.</para>
</listitem>
<listitem>
<para>Validate high order Indirect Buffer Descriptor bit is 0b1, else
respond with “Invalid Indirect Buffer Descriptor”</para>
</listitem>
<listitem>
<para>Validate that the indirect Buffer Descriptor address translates
through the LIOBN of the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property, else respond with “Invalid Indirect Buffer Descriptor”.</para>
</listitem>
<listitem>
<para>Copy the first 8 bytes at the translated Indirect Buffer Descriptor
address (Correlator) into the low order 8 bytes of the response prototype.</para>
</listitem>
<listitem>
<para>Validate that the Indirect Buffer Descriptor length field is at
least the total number of buffers indicated in the Count field in the
Request plus 1 (the Correlator), else respond with “Invalid Indirect Buffer Length”.</para>
</listitem>
<listitem>
<para>For each buffer indicated in the Indirect Buffer Descriptor:
<itemizedlist>
<listitem>
<para>Validate high order Buffer Descriptor bit is 0b1, else respond
with “Invalid Buffer Descriptor”</para>
</listitem>
<listitem>
<para>Validate that the Buffer Descriptor address translates through
the LIOBN of the first pane of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property, else respond with “Invalid Buffer Descriptor”.</para>
</listitem>
<listitem>
<para>If the Buffer Descriptor length field does not match the
buffer length of one of the buffer pools then:
<itemizedlist>
<listitem>
<para>If buffer lengths are assigned to all buffer pools,
then respond with “Invalid Buffer Length”</para>
</listitem>
<listitem>
<para>Else select an unassigned buffer pool, and assign its
length to match the length field of the Buffer Descriptor.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Enqueue the buffer descriptor onto the per service session
(“BOTTOM”) pool whose buffer length matches the length field of
the Buffer Descriptor, increment the Free Buffers in Pool count
for the pool.</para>
</listitem>
<listitem>
<para>Increment the Processed Buffers count.</para>
</listitem>
<listitem>
<para>Check if processing time still exists, if so continue to the
next buffer.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Copy the Processed Buffers count into the Count field (Byte 3) in
the response prototype.</para>
</listitem>
<listitem>
<para>Respond “Success”.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_of_the_vasi_add_buffer_indirect_crq_elem">
<title>Format of the VASI Add Buffer Indirect CRQ Elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<figure xml:id="figure_vasi_indirect_memory_buffer_format">
<title>Indirect Memory Buffer Format</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_vasi_indirect_memory_buffer_format.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_vasi_indirect_memory_buffer_format.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</simplesect>
</section>
<section xml:id="sec_vasi_message_upload">
<title>VASI Message Upload</title>
<para>The VASI Message Upload Command message (see
<xref linkend="figure_format_of_the_vasi_message_upload_crq_elements" />)
requests the receiving VSP to process the message. The “Control” field
defines how the VSP is suppose to process.</para>
<para>The valid message control codes are unique to the specific
VASI operation stream. See
<xref linkend="table_vasi_message_control_codes" />
for more details. The valid message sub-control codes are unique to each
VASI operation stream and defined control code. See
<xref linkend="table_vasi_message_subcontrol_codes" />
for more details. The 8 byte message data field is also operation
specific and unique to each control and sub-control code combination. See
<xref linkend="table_vasi_message_data" />
for more details.</para>
<para>The VASI Message Upload Response message indicates to the hypervisor
that the VSP has processed the message.</para>
<para>Status Values defined for the VASI Message Upload response message:
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Invalid TOP</para>
</listitem>
<listitem>
<para>Invalid Control</para>
</listitem>
<listitem>
<para>Invalid Sub-Control</para>
</listitem>
</itemizedlist>
</para>
<simplesect>
<title>Semantics for processing the VASI Message Upload Response Message:</title>
<itemizedlist>
<listitem>
<para>Validate the BOTTOM parameter for the caller; else respond
“Invalid BOTTOM”</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_of_the_vasi_message_upload_crq_elements">
<title>Format of the VASI Message Upload CRQ Elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_message_upload_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_message_upload_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<table frame="all" pgwide="1" xml:id="table_vasi_message_control_codes">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>VASI Message Control 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</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>Hypervisor pass-through: (Migration Only)<?linebreak?>
This control bit tells the VSP receiving a Message Upload
command to pass the command control, and data to the other
side of the migration for transmission to the hypervisor as a
VASI Message Download Command. The Sub-Control and data fields
are opaque to the VSP and not defined here.</para>
</entry>
</row>
<row>
<entry>
<para>0x02-0xFF</para>
</entry>
<entry>
<para>Reserved for future expansion</para>
<note><para> Message control codes are values not bit fields.</para></note>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vasi_message_subcontrol_codes">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>VASI Message Sub-Control Codes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Control Code</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Sub-Control Values</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>0x00-0xFF</para>
</entry>
<entry>
<para>Hypervisor defined and outside the scope of this architecture.</para>
</entry>
</row>
<row>
<entry>
<para>0x02-0xFF</para>
</entry>
<entry>
<para>0x00-0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_vasi_message_data">
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<title>VASI Message Data</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Control Code</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Sub-Control Bit Values</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>0x00-0xFF</para>
</entry>
<entry>
<para>Hypervisor defined and outside the scope of this architecture.</para>
</entry>
</row>
<row>
<entry>
<para>0x02-0xFF</para>
</entry>
<entry>
<para>0x00-0xFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</simplesect>
</section>
<section xml:id="sec_vasi_message_download">
<title>VASI Message Download</title>
<para>The VASI Message Download Command message (see
<xref linkend="figure_format_of_the_vasi_message_download_crq_elements" />)
passes the message data to the VASI Virtual IOA of the VASI Stream,
associated with the BOTTOM parameter, for processing.</para>
<para>The “Control” and “Sub-Control” fields define how the VASI Virtual IOA
is suppose to process the message.</para>
<para>The valid message control codes are unique to the specific
VASI operation stream. See
<xref linkend="table_vasi_message_control_codes" />
for more details. The valid message sub-control codes are unique to each
VASI operation stream and defined control code. See
<xref linkend="table_vasi_message_subcontrol_codes" />
for more details. The 8 byte message data field is also operation
specific and unique to each control and sub-control code combination. See
<xref linkend="table_vasi_message_data" />
for more details.</para>
<para>The VASI Message Download Response message indicates to the VSP that
the hypervisor that has processed the message.</para>
<para>Status Values defined for the VASI Message Download response message:
<itemizedlist spacing="compact" mark="none">
<listitem>
<para>Success</para>
</listitem>
<listitem>
<para>Hardware</para>
</listitem>
<listitem>
<para>Invalid BOTTOM</para>
</listitem>
<listitem>
<para>Invalid Control</para>
</listitem>
<listitem>
<para>Invalid Sub-Control</para>
</listitem>
</itemizedlist>
</para>
<simplesect>
<title>Semantics for processing the VASI Message Download Response Message:</title>
<itemizedlist>
<listitem>
<para>Construct VASI Signal Response message prototype (copy the low
order 14 bytes from the Request message to the response prototype).</para>
</listitem>
<listitem>
<para>Validate the BOTTOM parameter for the caller; else respond
“Invalid BOTTOM”</para>
</listitem>
<listitem>
<para>Insert the TOP recorded for the open BOTTOM into the response prototype.</para>
</listitem>
<listitem>
<para>Determine the VASI stream associated with the BOTTOM parameter.
If the “Control” or “Sub-Control” parameter is invalid for the VASI
operation stream represented by the BOTTOM parameter (refer to
<xref linkend="table_vasi_message_control_codes" />, and
<xref linkend="table_vasi_message_subcontrol_codes" />,
then respond “Invalid Control Code” or “Invalid Sub-Control Code”
respectively.</para>
</listitem>
</itemizedlist>
<figure xml:id="figure_format_of_the_vasi_message_download_crq_elements">
<title>Format of the VASI Message Download CRQ Elements</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/figure_format_vasi_message_download_crq_elem.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/figure_format_vasi_message_download_crq_elem.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</simplesect>
</section>
</section>
<section xml:id="sec_vasi_virtual_ioa_devtree">
<title>VASI Virtual IOA Device Tree</title>
<table frame="all" pgwide="1" xml:id="table_vasi_node_properties">
<title>Properties of the VASI Node in a Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="left" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="60*" align="left" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>IBM,VASI</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>IBM,VASI-1</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>IBM,VASI-1</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and
persistent location code associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per <citetitle>IEEE 1275</citetitle> specifying the
register addresses, used as the unit address (unit
ID), associated with this virtual IOA presented as
an encoded array as with <emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
value shall be 0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
property used for unit address no actual locations used, therefore, the size field
has zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window
associated with this virtual IOA presented as an encoded
array of tripples; each triple consisting of three values (LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis> respectively.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual
IOA presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell
containing the interrupt source number, and the
second cell containing the sense code 0 indicating positive
edge triggered. The interrupt source number being the value
returned by the H_XIRR or H_IPOLL hcall().</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this node.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
size format. The property value specifies the number
of cells that are used to encode the size field of
dma-window properties. If the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
property is missing, the default value is the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis>
property for the parent package.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>Property name, to define the package’s dma address
format. The property value specifies the number
of cells that are used to encode the physical address field of
child's dma-window properties. If the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
property is missing, the default value is the
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
property for the parent package.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#buffer-pools&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name to define number, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
of different data buffer size pools
supported by the VASI virtual IOA service sessions.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,crq-size&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name to define the size, in bytes, of the VASI virtual IOA CRQ; encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,#vasi-streams&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name to define the number of simultaneous
unique VASI stream IDs that may be supported by
the VASI virtual IOA CRQ; encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vasi_hcalls">
<title>VASI Support hcall()s</title>
<para>The hcall()s of this section support the VASI option. H_DONOR_OPERATION supplies the hypervisor with processor
cycles to perform administrative services. H_VASI_SIGNAL allows partitions to signal anomalous conditions such as
the need to abort the administrative service stream without having to have an open VASI virtual IOA. While the
H_VASI_STATE allows partitions that do not have an open VASI virtual IOA for a given VASI stream ID to poll the
state of their administrative service streams.</para>
<section xml:id="sec_vasi_h_donor_operations">
<title>H_DONOR_OPERATION</title>
<para>This hcall() supplies donor partition cycles to perform hypervisor operations for a given VASI Stream. The TOP/BOTTOM
parameter indicates the VASI stream, and thus a specific operating context relative to the caller and callee. The
cycles donated by any and all TOP/BOTTOMs associated with the VASI Stream are combined by the platform to perform
the needed processing for the stream. A platform may use the cycles from different TOP/BOTTOM pairs to create
parallel processes to improve the stream performance.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected final Return code */
/* H_IN_PROGRESS: The requested operation has not */
/* completed call again */
/* H_LongBusyOrder*: Wait the indicated time and call again */
/* H_Parameter: The handle parameter is invalid */
/* H_Aborted: The operation received an abort signal*/
/* H_Hardware: The hardware experienced a fault */
/* causing the function to fail. */
hcall ( const uint64 H_DONOR_OPERATION, /* Use my processor to perform platform */
/* operations */
uint64 TOP/BOTTOM_ID); /* Opaque handles of a specific VASI operation */
/* stream relative to the caller and callee.*/]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>TOP/BOTTOM_ID (The opaque handles of a specific VASI operation stream relative to the caller and callee.)</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>If the TOP/BOTTOM_ID parameter is invalid relative to the calling partition, return H_Parameter.</para>
</listitem>
<listitem>
<para>If the VASI stream is in the aborted state, return H_Aborted.</para>
</listitem>
<listitem>
<para>Perform the next operation associated with the specified VASI stream. Note the amount of processing performed on
any one call is limited by the interrupt hold off constraints of standard hypervisor calls. (The format of the platform
operation state structure is outside of the scope of this architecture.)</para>
</listitem>
<listitem>
<para>If the specific VASI stream operation is fully complete, return H_Success.</para>
</listitem>
<listitem>
<para>If the specific VASI stream requires more processing to fully complete the platform operation and is not blocked
waiting for asynchronous agent(s), return H_IN_PROGRESS.</para>
</listitem>
<listitem>
<para>If the VASI stream is blocked waiting for asynchronous agent(s), return H_LongBusyOrder* (where * is the appropriate
expected waiting time).</para>
</listitem>
</itemizedlist>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_h_donor_operations"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must implement the H_DONOR_OPERATION hcall() following
the syntax and semantics of
<xref linkend="sec_vasi_h_donor_operations" />.</para>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
</section>
<section xml:id="sec_h_vasi_signal">
<title>H_VASI_SIGNAL</title>
<para>This hcall() signals the condition specified by the “signal code”
parameter to the VASI Virtual IOA of the VASI Stream
associated with the “handle” parameter; optionally, a non-zero
“reason code” may be associated with the signal code so
that firmware may record the signal using facilities and methods
that are outside the scope of this architecture.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected final Return code */
/* H_Parameter: The VASI_Stream_ID parameter is invalid */
/* H_NOOP: The signal_code value was invalid for the */
/* current state.*/
/* H_P2: The signal_code value was invalid*/
/* H_Hardware: The hardware experienced a fault causing the */
/* function to fail. */
hcall ( const uint64 H_VASI_SIGNAL, /* Signal the VASI operation stream of */
/* condition signal_code. */
uint64 handle, /* Opaque handle of a specific VASI operation stream */
/* relative to the caller and callee.*/
int64 signal_code, /* signal_code value */
int64 reason_code);/* reason_code value */]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>handle -- the VASI Stream ID (The opaque handle of a specific VASI operation stream.)</para>
</listitem>
<listitem>
<para>signal_code -- one of the values listed in
<xref linkend="table_vasi_signal_codes" />
right justified with high order bytes zero.</para>
</listitem>
<listitem>
<para>reason_code -- Code user gives as reason for signal right
justified with high order bytes zero -- The value is simply
transported not checked by the platform.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>If the “handle” parameter is invalid relative to the calling partition, then return H_Parameter.</para>
</listitem>
<listitem>
<para>If the “signal_code” is invalid based upon the values listed in
<xref linkend="table_vasi_signal_codes" />,
then return H_P2.</para>
</listitem>
<listitem>
<para>If the “signal_code” is valid for the current VASI stream state,
initiate the processing defined for the “signal_code”;
else return H_NOOP.</para>
</listitem>
</itemizedlist>
<table frame="all" pgwide="1" xml:id="table_vasi_signal_codes">
<title>VASI Signal Codes</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="30*" align="left" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="15*" align="center" />
<colspec colname="c6" colwidth="15*" align="center" />
<thead valign="middle">
<row>
<entry morerows="1">
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry morerows="1" align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">VASI Operation Stream</emphasis>
</para>
</entry>
<entry namest="c5" nameend="c6">
<para>
<emphasis role="bold">Valid for Interface</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">VASI Signal Message</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">H_VASI_SIGNAL</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Null</para>
</entry>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Not used (invalid)</para>
</entry>
<entry>
<para>All</para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Cancel</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Gracefully cancel processing if possible</para>
</entry>
<entry>
<para>Partition Migration<?linebreak?>Partition Hibernation</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Y</para>
</entry>
</row>
<row>
<entry>
<para>Abort</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Immediately halt function</para>
</entry>
<entry>
<para>Partition Migration<?linebreak?>Partition Hibernation</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Suspend</para>
</entry>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>Suspend target partition</para>
</entry>
<entry>
<para>Partition Migration<?linebreak?>Partition Hibernation</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Complete</para>
</entry>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>Complete paging operation</para>
</entry>
<entry>
<para>Paging</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Enable</para>
</entry>
<entry>
<para>0x5</para>
</entry>
<entry>
<para>Enabling paging operation</para>
</entry>
<entry>
<para>Paging</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Failover</para>
</entry>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>Failover operation</para>
</entry>
<entry>
<para>Partition Migration</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>0x7-0xFFFF</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>All</para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>N</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_h_vasi_signal"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must implement the H_VASI_SIGNAL hcall() following the syntax and semantics of
<xref linkend="sec_h_vasi_signal" />.</para>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
</section>
<section xml:id="sec_h_vasi_state">
<title>H_VASI_STATE</title>
<para>This hcall() returns the state of the specific VASI operation stream.</para>
<simplesect>
<title>Syntax:</title>
<programlisting><![CDATA[int64 /* H_Success: Expected final Return code */
/* H_Parameter: The handle parameter is invalid */
/* H_Hardware: The hardware experienced a fault causing the */
/* function to fail. */
hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
/* associated with handle */
uint64 handle);/* The opaque handle of a specific VASI operation stream */
/* relative to the caller and callee.*/]]></programlisting>
</simplesect>
<simplesect>
<title>Parameters:</title>
<itemizedlist>
<listitem>
<para>handle -- the VASI Stream ID (The opaque handle of a specific VASI operation stream relative to the caller and callee.)</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Semantics:</title>
<itemizedlist>
<listitem>
<para>If the “handle” parameter is invalid relative to the calling partition, return H_Parameter.</para>
</listitem>
<listitem>
<para>Else enter the value of the VASI state variable (see
<xref linkend="table_vasi_partition_migration_states" />)
for the indicated stream into R4 and return H_Success</para>
</listitem>
</itemizedlist>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_h_vasi_state"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VASI option:</emphasis>
The platform must implement the H_VASI_STATE hcall() following the syntax and semantics of
<xref linkend="sec_h_vasi_state" />.</para>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
</section>
</section>
<section xml:id="sec_vasi_op_stream_specs">
<title>VASI Operation Stream Specifications</title>
<para>This section defines the usage of VASI to accomplish specific administrative services. Each section specifies the valid
VASI state codes, state transitions, and reason codes, the action of the VASI virtual IOA in each state and the expected
behavior of the VASI device driver in order to achieve the operational goal.</para>
<table frame="all" pgwide="1" xml:id="table_vasi_stream_services_for_partition_migration">
<title>VASI Stream Services for Partition Migration</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="65*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Unused</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Source Mover for Partition Migration</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>VASI device will be used to extract partition state from the source platform to the target
platform using VASI Operations (Write sequential) to extract partition state, and VASI
Download commands to give source platform paging requests. See
<xref linkend="sec_vasi_partition_migration" />.</para>
</entry>
</row>
<row>
<entry>
<para>Target Mover for Partition Migration</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>VASI device will be used to insert migrating partition’s state to the target platform. VASI
Download requests will be used to give platform firmware partition state, and VASI
Operations (Write sequential) will be used by platform firmware to give paging requests to
the Mover partition to deliver to the source platform.See
<xref linkend="sec_vasi_partition_migration" />.</para>
</entry>
</row>
<row>
<entry>
<para>Pager for the CMO option</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>VASI device will be used to handle CMO paging requests See
<xref linkend="sec_vasi_memory_overcommit" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<section xml:id="sec_vasi_partition_migration">
<title>Partition Migration</title>
<para><xref linkend="table_vasi_stream_services_for_partition_migration" />
defines the VASI Services for Partition Migration for use in the VASI Open CRQ request, as defined in
<xref linkend="sec_vasi_open" />.</para>
<para><emphasis role="bold">Requirements:</emphasis></para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
If any partition code uses the value of the processor PVR to modify its operation, to ensure
valid operation after the resume from suspension, prior to executing any such
modified operation code, partition code must reread the PVR value and be prepared to remodify its operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
In order that LAN communication partners may learn of the
new MAC address that may be associated with a migrated partition, the migrated partition must generate
“gratuitous ARP” messages. It is suggested that these “gratuitous ARP” messages be sent at the rate of once
per second between the time that the migrating partition resumes and the H_VASI_STATE hcall() responds
with “Completed”.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
To maintain the platform capability to perform live firmware
updates, the OS must call the
<emphasis>ibm,activate-firmware</emphasis> RTAS service after waking from a migration suspension.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
The platform must implement the ILLAN option (see
<xref linkend="dbdoclet.50569350_23147" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
Platform firmware must support both immediate and indirect
data in its VASI Download data buffers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
If multiple partition migrations are being performed using a
single VASI device, to ensure none of the migrations are starved, partition software must call
H_DONOR_OPERATION with TOP/BOTTOMs associated with each migration (VASI Stream ID).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
If the platform detects any unrecoverable error in processing
a VASI Download command, it must transition the associated VASI stream to the “Aborted” state.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_migration"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Migration Option:</emphasis>
The VASI stream ID for the specific high level migration
function must be the same value in both the source and target platforms.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Programming Note:</emphasis>
If partition software wishes to get an accurate count of the number of bytes to be transferred using
the VASI Progress CRQ message, it should be issued immediately following a VASI open and before any cycles
are donated for that migration via H_DONOR_OPERATION.</para>
<section xml:id="sec_vasi_partition_migration_abort_reasons">
<title>Partition Migration Abort Reason Codes</title>
<para><xref linkend="table_partition_migration_abort_codes" />
defines the Abort reason code layout for Partition Migration for use with the
H_VASI_SIGNAL hypervisor call and the VASI Signal and State CRQ requests, as defined in
<xref linkend="sec_vasi_state" />.</para>
<table frame="all" pgwide="1" xml:id="table_partition_migration_abort_codes">
<title>Partition Migration Abort Reason Codes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="70*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Aborting Entity</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>1=Orchestrator<?linebreak?>
2=VSP providing VASI partition source migration service<?linebreak?>
3=Partition Firmware<?linebreak?>
4=Platform Firmware<?linebreak?>
5=VSP providing VASI partition target migration service<?linebreak?>
6=Migrating partition</para>
</entry>
</row>
<row>
<entry>
<para>Detailed Error</para>
</entry>
<entry>
<para>1-3</para>
</entry>
<entry>
<para>Bytes one through three of the reason code are opaque values, architected by
individual aborting entities.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vasi_partition_migration_failover_reason_codes">
<title>Partition Migration Failover Reason Codes</title>
<para><xref linkend="table_partition_migration_failover_codes" />
defines the Failover reason code layout for Partition Migration for use with the H_VASI_SIGNAL hypervisor call and the VASI Signal &amp; State CRQ requests, as defined in
<xref linkend="sec_vasi_state" />.</para>
<table frame="all" pgwide="1" xml:id="table_partition_migration_failover_codes">
<title>Partition Migration Failover Reason Codes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="70*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte:bit - Byte:bit</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Failing Entity</para>
</entry>
<entry>
<para>0:0 - 0:7</para>
</entry>
<entry>
<para>1=Orchestrator<?linebreak?>
2=VSP providing VASI partition source migration service<?linebreak?>
3=Partition Firmware<?linebreak?>
4=VSP providing VASI partition target migration service</para>
</entry>
</row>
<row>
<entry>
<para>Failover Direction</para>
</entry>
<entry>
<para>1:0-1:1</para>
</entry>
<entry>
<para>0=Failover direction not indicated<?linebreak?>
1=Failover to this MSP<?linebreak?>
2=Failover from this MSP</para>
</entry>
</row>
<row>
<entry>
<para>Error Type</para>
</entry>
<entry>
<para>1:2-1:2</para>
</entry>
<entry>
<para>0=Fatal error<?linebreak?>
1=Non-fatal error</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>1:3-1:7</para>
</entry>
<entry>
<para>Reserved for future expansion</para>
</entry>
</row>
<row>
<entry>
<para>Detailed Error</para>
</entry>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>Bytes two and three of the reason code are opaque values, architected by
individual aborting entities.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vasi_partition_migration_states">
<title>Partition Migration VASI States</title>
<para>This section defines the partition migration VASI states as used in the VASI State request CRQ message and as returned
from the H_VASI_STATE hcall.</para>
<table frame="all" pgwide="1" xml:id="table_vasi_partition_migration_states">
<title>VASI Migration Session States</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="60*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Invalid</para>
</entry>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>This state is defined on both the source and destination platform
and indicates either that the specified Stream ID is not valid (or
is no longer valid) or the invoking partition is not authorized to
utilize the Stream ID.</para>
</entry>
</row>
<row>
<entry>
<para>Enabled</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>This state is defined on both the source and destination platform
and indicates that the partition has been enabled for migration
but has not progressed beyond this initial state.</para>
<para>The transition to this state is triggered by events outside of the
scope of PAPR.</para>
<para>The partition on the source server transitions to this state first
and then the partition on the destination server.</para>
</entry>
</row>
<row>
<entry>
<para>Aborted</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>This state is defined on both the source and the destination
platform and indicates that the abort processing has completed.</para>
<para>If the migration has been aborted, this is the final state of the
migration and platform firmware ensures that all interested
partitions see this state at least once. Platform firmware
continues to return this state until events outside of the scope of
PAPR terminate the operation and all interested partitions have
seen this final state.</para>
<para>In this state VASI download request information is flushed,
returning success status. VASI signal requests other than
“abort” are treated as an invalid state transition.
The transition to this state occurs on the two servers
independently and thus it is a race condition which server
transitions to this state first.</para>
</entry>
</row>
<row>
<entry>
<para>Suspending</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>This state is defined only on the source platform and indicates
that the partition is in the process of suspending itself. When the
migrating partition sees this state, it enters its suspension
sequence that concludes with the call to ibm,suspend-me.</para>
<para>The transition to this state occurs when the source VSP directs
platform firmware to suspend the partition via a VASI Signal
request (Signal Code = Suspend) on the VASI device.</para>
</entry>
</row>
<row>
<entry>
<para>Suspended</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>This state is defined only on the source platform and indicates
that the partition has suspended itself via the ibm,suspend-me
RTAS call. This is the point in the sequence where platform
firmware will reject attempts by the user to abort the migration.</para>
</entry>
</row>
<row>
<entry>
<para>Resumed</para>
</entry>
<entry>
<para>5</para>
</entry>
<entry>
<para>This state is defined on both the source and destination platform
and indicates that the partition has resumed execution on the
destination platform.</para>
<para>The transition to this state occurs on the destination platform
first when it receives the dirty page bitmap from the source
platform firmware. It is at this point the virtual processors of the
migrating partition are dispatched on the destination platform.</para>
</entry>
</row>
<row>
<entry>
<para>Completed</para>
</entry>
<entry>
<para>6</para>
</entry>
<entry>
<para>This state is defined on both the source and destination platform
and indicates that the migration has completed and all partition
state has been transferred to the destination platform. This is the
final state of the migration and platform firmware ensures that
all interested partitions see this state at least once. Platform
firmware continues to return this state until events outside of the
scope of PAPR terminate the operation and all interested
partitions have seen this final state.</para>
<para>The transition to this state occurs on the source platform first as
soon as all of the residual state of the migrating partition has
been successfully transferred to the destination platform. The
transition to this state on the destination platform occurs when
all of the partition state has been received from the source
platform.</para>
<para>For an inactive migration, the partition is transferred as a single
unit so the partition in the destination platform just moves from
Enabled to Completed on a successful inactive migration.</para>
</entry>
</row>
<row>
<entry>
<para>Failover</para>
</entry>
<entry>
<para>7</para>
</entry>
<entry>
<para>This state is defined on both the source and the destination
platform and indicates one or more of the active MSP pairs has
failed and the operation will continue on the remaining MSP pairs.
This state indicates that a failover is in progress. The Failover
state is the final migration state for the MSPs that are failing,
for all other components failover is not the final state as the
migration will either continue on or abort.</para>
<note>
<para>The Failover state will never be returned by the H_VAS_STATE
hcall but will be delivered to the MSP via the VASI
State request CRQ.</para>
</note>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section xml:id="sec_vasi_partition_hibernation">
<title>Partition Hibernation</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
The platform must ensure that all hibernating partition dynamic
reconfiguration operations are complete prior to signaling suspension of the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
If any partition code uses the value of the processor PVR
to modify its operation, after the resume from suspension, but prior to executing any such modified operation
code, it must reread the PVR value and be prepared to remodify its operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
In order that LAN communication partners may learn of
the new MAC address that may be associated with a hibernated partition the hibernated partition must generate
“gratuitous ARP” messages. It is suggested that these “gratuitous ARP” messages be sent at the rate of
once per second between the time that the hibernated partition resumes and the H_VASI_STATE hcall() responds
with “Completed”.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
To maintain the platform capability to perform live firmware
updates, the OS must call the <emphasis>ibm,activate-firmware</emphasis>
RTAS service after waking from a hibernation suspension.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
The platform must implement the ILLAN option (see
<xref linkend="dbdoclet.50569350_23147" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vasi_partition_hibernation"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Hibernation Option:</emphasis>
The VASI stream ID for the specific high level migration
function must be the same value for both the suspend and wake phases.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_vasi_memory_overcommit">
<title>Cooperative Memory Overcommitment</title>
<para>The CMO option defines the stream service value 3 for “Pager”. The Pager VASI device is used to page out paging partition
state to the VASI Server Partition (VSP) using VASI Operation requests (Write indexed) and also to page in partition
state from the VSP using VASI Operation requests (Read indexed). The Pager VASI service utilizes a subset of
the VASI Operation request architecture; specifically in the VASI Operation Request Specifier structure, the File offset
of the start for indexed operations field (Bytes 9:15) is not used (value = 0x00); the scatter/gather list is a series of 1 –
N sub operation specifications each starting with the positioning of the file cursor using a type 0xC0 control element to
establish the file block location, optionally followed by a type 0x40 control element to position the file cursor to a byte
within the established file block, this is followed by one and only one type 0x80 control element per sub operation to
transfer the sub operation data. The VASI Operation Request Specifier structure terminates as always with a type 0x00
control element with a segment length field of 0x000000.</para>
<para>When a Pager VASI service aborts, the reason code returned is per
<xref linkend="table_cmo_vasi_abort_codes" />.
The Pager Service VASI States as in the state request CRQ message and as returned from the
H_VASI_STATE hcall are as defined in
<xref linkend="table_cmo_vasi_states" />.</para>
<table frame="all" pgwide="1" xml:id="table_cmo_vasi_abort_codes">
<title>CMO VASI Abort Reason Codes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="55*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Entity (who is issuing state change or signal)</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>1 = VASI<?linebreak?>
2 = I/O Provider<?linebreak?>
3 = Platform Firmware</para>
</entry>
</row>
<row>
<entry>
<para>Detailed Reason</para>
</entry>
<entry>
<para>1-3</para>
</entry>
<entry>
<para>Bytes one through three of the reason code are opaque values, architected by individual entities.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1" xml:id="table_cmo_vasi_states">
<title>CMO VASI States</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" align="left" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Invalid</para>
</entry>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>This state indicates that the specified Stream ID is not valid (or is no longer valid) or the invoking
partition is not authorized to utilize the Stream ID.</para>
</entry>
</row>
<row>
<entry>
<para>Disabled</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>This state indicates that the specified Stream ID is valid, but the stream has not been yet opened
by the VSP providing VASI paging service. The transition to this state is triggered by events
outside of the scope of PAPR.</para>
</entry>
</row>
<row>
<entry>
<para>Suspended</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>This state indicates that the specified Stream ID is valid, but the client partition has not yet been
powered on</para>
</entry>
</row>
<row>
<entry>
<para>Enabled</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>This state indicates that the stream has been opened by the VSP providing VASI paging service
and the client partition is powered on</para>
</entry>
</row>
<row>
<entry>
<para>Stopped</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>This state indicates that the specified Stream ID is valid, however platform firmware is no longer
using the stream to perform paging. The transition to this state is triggered by events outside of the
scope of PAPR.</para>
</entry>
</row>
<row>
<entry>
<para>Completed</para>
</entry>
<entry>
<para>5</para>
</entry>
<entry>
<para>This state indicates that paging has been terminated for this stream by a request to halt paging for
this Stream ID.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569364_64078">
<title>Virtual Fibre Channel (VFC) using NPIV</title>
<para>N_Port ID Virtualization (NPIV) is part of the Fibre Channel (FC)
standards. NPIV allows multiple World Wide Port Names (WWPNs) to be mapped
to a single physical port of a FC adapter. This section defines a Virtual
Fibre Channel (VFC) interface to a server partition interfacing to a
physical NPIV adapter that allows multiple partitions to share a physical
port using different WWPNs. The implementation support is provided by code
running in a server partition that uses the mechanisms of the Reliable
Command/Response Transport and Logical Remote DMA of the Synchronous VIO
Infrastructure to service I/O requests for code running in a client
partition. The client partition appears to enjoy the services of its own FC
adapter (see
<xref linkend="dbdoclet.50569348_51946" />) with a WWPN visible to the FC
fabric. The terms server and client partitions refer to platform partitions
that are respectively servers and clients of requests, usually I/O
operations, using the physical I/O adapters (IOAs) that are assigned to the
server partition. This allows a platform to have more client partitions
than it may have physical I/O adapters because the client partitions share
I/O adapters via the server partition.</para>
<para>The VFC model makes use of Remote DMA which is built upon the
architecture specified in the following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
<section>
<title>VFC and NPIV General</title>
<para>This section contains an informative outline of the architectural
intent of the use of VFC and NIPV, and it assumes the user is familiar
with
<xref linkend="dbdoclet.50569351_81654" /> concerning VSCSI architecture
and the with the FC standards. Other implementations of the server and
client partition code, consistent with this architecture, are possible
and may be preferable.</para>
<para>The client partition provides the virtual equivalent of a single
port FC adapter via each VFC client IOA. The platform, through the
partition definition, provides means for defining the set of virtual
IOA&#8217;s owned by each partition and their respective location codes.
The platform also provides, through partition definition, instructions to
connect each client partition&#8217;s VFC client IOA to a specific server
partition&#8217;s VFC server IOA. The mechanism for specifying this
partition definition is beyond the scope of this architecture. The human
readable handle associated with the partition definition of virtual IOAs
and their associated interconnection and resource configuration is the
virtual location code. The OF unit address (<emphasis role="bold"><literal>Unit ID</literal></emphasis>) remains the invariant handle upon which the
OS builds its &#8220;physical to logical&#8221; configuration. The
platform also provides a method to assign unique WWPNs for each VFC
client adapter. The port names are used by a SAN administrator to grant
access to storage to a client partition. The mechanism for allocating
port names is beyond the scope of this architecture.</para>
<para>The client partition&#8217;s device tree contains one or more nodes
notifying the partition that it has been assigned one or more virtual
adapters. The node&#8217;s
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> properties notify the
partition that the virtual adapter is a VFC adapter. The
<emphasis role="bold"><literal>unit address</literal></emphasis> of the node is used by the client
partition to map the virtual device(s) to the OS&#8217;s corresponding
logical representations. The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property communicates
the size of the RTCE table window panes that the hypervisor has
allocated. The node also specifies the interrupt source number that has
been assigned to the Reliable Command/Response Transport connection and
the RTCE range that the client partition device driver may use to map its
memory for access by the server partition via Logical Remote DMA. The
client partition also reads it's WWPNs from the device tree. Two WWPNs
are presented to the client in the properties
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-1&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-2&#8221;</literal></emphasis>, and the server tells
the client, through a CRQ protocol exchange, which one of the two to use.
The client partition, uses the four hcall()s associated with the Reliable
Command/Response Transport facility to register and deregister its CRQ,
manage notification of responses, and send command requests to the server
partition.</para>
<para>The server partition&#8217;s device tree contains one or more
node(s) notifying the partition that it is requested to supply VFC
services for one or more client partitions. The unit address (
<emphasis role="bold"><literal>Unit ID)</literal></emphasis> of the node is used by the server partition
to map to the local logical devices that are represented by this VFC
device. The node also specifies the interrupt source number that has been
assigned to the Reliable Command/Response Transport connection and the
RTCE range that the server partition device driver may use for its copy
Logical Remote DMA. The server partition uses the four hcall()s
associated with the Reliable Command/Response Transport facility to
register and deregister its Command request queue, manage notification of
new requests, and send responses back to the client partition. In
addition, the server partition uses the hcall()s of the Logical Remote
DMA facility to manage the movement of commands and data associated with
the client requests.</para>
<para>The client partition, upon noting the device tree entry for the
virtual adapter, loads the device driver associated with the value of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property. The device driver,
when configured and opened, allocates memory for its CRQ (an array, large
enough for all possible responses, of 16 byte elements), pins the queue
and maps it into the I/O space of the RTCE window specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property using the
standard kernel mapping services that subsequently use the H_PUT_TCE
hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next,
I/O request control blocks (within which the I/O requests commands are
built) are allocated, pinned, and mapped into I/O address space. Finally,
the device driver registers to receive control when the interrupt source
specified in the virtual IOA&#8217;s device tree node signals.</para>
<para>Once the CRQ is setup, the device driver queues an Initialization
Command/Response with the second byte of &#8220;Initialize&#8221; in
order to attempt to tell the hosting side that everything is setup on the
hosted side. The response to this send may be that the send has been
dropped or has successfully been sent. If successful, the sender should
expect back an Initialization Command/Response with a second byte of
&#8220;Initialization Complete,&#8221; at which time the communication
path can be deemed to be open. If dropped, then the sender waits for the
receipt of an Initialization Command/Response with a second byte of
&#8220;Initialize,&#8221; at which time an &#8220;Initialization
Complete&#8221; message is sent, and if that message is sent
successfully, then the communication path can be deemed to be
open.</para>
<para>For a partition booted on P9 Firmware or newer, the client partition uses
the hcall()s associated with the Subordinate CRQ Transport facility to register
and deregister any sub-CRQs necessary for the operations of the VFC. Once the
main CRQ connection is complete between the client and the server, the client
receives from the server the number of sub-CRQs that can be supported on the
client side. The client allocates memory for the first sub-CRQ (an array, large
enough for all possible responses, of 32 byte elements), pins the queue and
maps it into the I/O space of the RTCE window specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property using the standard kernel mapping services that subsequently use the
H_PUT_TCE hcall(). The queue is then registered using the H_REG_SUB_CRQ hcall().
This process continues until all desired sub-CRQs are registered or until the
H_REG_SUB_CRQ hcall() indicates that the resources allocated to the client for
sub-CRQs for the virtual IOA have already been allocated (H_Resource returned).
Interrupt numbers for the Sub-CRQs that have been registered, are returned by
the H_REG_SUB_CRQ hcall() (See
<xref linkend="dbdoclet.50569348_63838" />).</para>
<para>Once all the CRQs and Sub-CRQs are setup, the communications between the
client and server device drivers may commence for purposes of further setup
operations, and then normal I/O requests, error communications, etc. The
protocol for this communication is beyond the scope of this architecture.
When a partition calls H_FREE_CRQ or crashes, the Hypervisor notifies the
partner partition by placing a Transport Event in the partner’s main CRQ.
Following the main CRQ, a 32-byte transport event will also be sequentially
placed on active partner Subordinate queues. For Partition Mobility, in the
event of an active migration, VFC client and server will receive a 32-byte Partner
Partition Suspended transport event on the main CRQ and sequentially on any
active Subordinate queues. The 32-byte Subordinate CRQ transport event uses
the same Format byte (second byte) and is as defined in
<xref linkend="dbdoclet.50569348_93265" />).
For Partition Mobility, if the partition is not booted in at least P9 Base
Compatibility mode, the Sub-CRQs will not be migrated to the target, however,
all associated RTCE mapped memory will be migrated. Upon Partition Mobility abort,
the Sub-CRQs will remain intact on the source.</para>
<para>For a platform that does not support the Subordinate CRQ Transport
facility or is not booted on P9 Firmware or newer, the partition should
expect H_Parameter from H_REG_SUB_CRQ.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> On some earlier levels
of P9 Firmware, the partition may need to be booted in P9 Base Compatibility
mode or newer, else the partition should expect H_Parameter from H_REG_SUB_CRQ.
In later levels of P9 Firmware (FW930 and later), the partition may be able to
successfully H_REG_SUB_CRQ in older compatibility modes; however, all Sub-CRQs
will not be migrated to the target to maintain compatibility.</para>
<para>When the VFC Adapter device driver receives an I/O request from one
of the FC device head drivers, it executes the following sequence. First
an I/O request control block is allocated. Then it builds the FC
Information Unit (FC IU) request within the control block, adds a
correlator field (to be returned in the subsequent response), I/O maps
any target memory buffers and places their DMA descriptors into the I/O
request control block. With the request constructed in the I/O request
control block, the driver constructs a DMA descriptor (Starting Offset,
and length) representing the FC IU within the I/O request control block.
It also constructs a DMA descriptor for the FC Response Unit. Lastly, the
driver passes the I/O request&#8217;s DMA descriptor to the server
partition using the H_SEND_CRQ hcall(). Provided that the H_SEND_CRQ
hcall() succeeds, the VFC Adapter device driver returns, waiting for the
response interrupt indicating that a response has been posted by the
server partition to the device driver&#8217;s response queue. The
response queue entry contains the summary status and request correlator.
From the request correlator, the device driver accesses the I/O request
control block, the summary status, and the FC Response Unit and
determines how to complete the processing of the I/O request.</para>
<para>Notice that the client partition only uses the Reliable
Command/Response Transport primitives; it does not use the Logical Remote
DMA primitives. Since the server partition&#8217;s RTCE tables are not
authorized for access by the client partition, any attempt by the client
partition to modify server partition memory would be prevented by the
hypervisor. RTCE table access is granted on a connection by connection
basis (client/server virtual device pair). If a client partition happens
to be serving some other logical device, then the partition is entitled
to use Logical Remote DMA for the virtual devices that is serving.</para>
<para>The server partition, upon noting the device tree entry for the
virtual adapter, loads the device driver associated with the value of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property. The device driver,
when configured and opened, allocates memory for its request queue (an
array, large enough for all possible outstanding requests, of 16 byte
elements). The driver then pins the queue and maps it into I/O space, via
the kernel&#8217;s I/O mapping services that invoke the H_PUT_TCE
hcall(), using the first window pane specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. The queue
is then registered using the H_REG_CRQ hcall(). Next, I/O request control
blocks (within which the I/O request commands are built) are allocated,
pinned, and I/O mapped. Finally the device driver registers to receive
control when the interrupt source specified in the virtual IOA&#8217;s
device tree node signals.</para>
<para>Once the CRQ is setup, the device driver queues an Initialization
Command/Response with the second byte of &#8220;Initialize&#8221; in
order to attempt to tell the hosted side that everything is setup on the
hosting side. The response to this send may be that the send has been
dropped or has successfully been sent. If successful, the sender should
expect back an Initialization Command/Response with a second byte of
&#8220;Initialization Complete,&#8221; at which time the communication
path can be deemed to be open. If dropped, then the sender waits for the
receipt of an Initialization Command/Response with a second byte of
&#8220;Initialize,&#8221; at which time an &#8220;Initialization
Complete&#8221; message is sent, and if that message is sent
successfully, then the communication path can be deemed to be
open.</para>
<para>When the server partition&#8217;s device driver receives an I/O
request from its corresponding client partition&#8217;s VFC adapter
drivers, it is notified via the interrupt registered for above. The
server partition&#8217;s device driver selects an I/O request control
block for the requested operation. It then uses the DMA descriptor from
the request queue element to transfer the FC IU request from the client
partition&#8217;s I/O request control block to its own (allocated above),
using the H_COPY_RDMA hcall() through the second window pane specified in
the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property. The server
partition&#8217;s device driver then uses kernel services, that are
extended, to register the I/O request&#8217;s DMA descriptors into
extended capacity cross memory descriptors (ones capable of recording the
DMA descriptors). These cross memory descriptors are later mapped by the
server partition&#8217;s physical device drivers into the physical I/O
DMA address space of the physical I/O adapters using the kernel services,
that have been similarly extended to call the H_PUT_RTCE hcall(), based
upon the value of the LIOBN field reference by the cross memory
descriptor. At this point, the server partition&#8217;s VFC device driver
delivers what appears to be a FC IU request to be routed through the
server partition&#8217;s adapter driver. When the request completes, the
server partition&#8217;s VFC device driver is called through a registered
entry point and it packages the summary status along with the request
correlator into a response message that it sends to the client partition
using the H_SEND_CRQ hcall(), then recycles the resources recorded in the
I/O request control block, and the block itself.</para>
<para>The LIOBN value in the second window pane of the server
partition&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property is intended
to be an indirect reference to the RTCE table of the client partition.
If, for some reason, the physical location of the client
partition&#8217;s RTCE table changes or it becomes invalid, this level of
indirection allows the hypervisor to determine the current target without
changing the LIOBN number as seen by the server partition. The H_PUT_TCE
and H_PUT_RTCE hcall()s do not map server partition memory into the
second window pane; the second window pane is only available for use by
server partition via the Logical RDMA services to reference memory mapped
into it by the client partition&#8217;s IOA.</para>
<para>This architecture does not specify the payload format of the
requests or responses. However, the architectural intent is supplied in
the following tables for reference.</para>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>General Form of Reliable CRQ Element</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="55*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Subfield Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Header</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Contains Element Valid Bit plus Event Type Encodings (see
<xref linkend="dbdoclet.50569348_49382" />).</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry morerows="1">
<para>Payload</para>
</entry>
<entry>
<para>Format/Transport Event Code</para>
</entry>
<entry>
<para>For Valid Command Response Entries, see
<xref linkend="dbdoclet.50569364_41722" />. For Transport Event
Codes see
<xref linkend="dbdoclet.50569348_93265" />.</para>
</entry>
</row>
<row>
<entry>
<para>2-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Format Dependent.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569364_41722">
<title>Example Reliable CRQ Entry Format Byte Definitions
for VFC</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Format Byte Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>Unused</para>
</entry>
</row>
<row>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>VFC Requests</para>
</entry>
</row>
<row>
<entry>
<para>0x02 - 0x03</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x04</para>
</entry>
<entry>
<para>Management Datagram</para>
</entry>
</row>
<row>
<entry>
<para>0x05 - 0xFE</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Example VFC Command Queue Element</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>VFC Requests</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x04</para>
</entry>
<entry>
<para>Management Datagram</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>4-7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Length of the request block to be transferred</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>I/O address of beginning of request</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
<table frame="all" pgwide="1">
<title>Example VFC Response Queue Element</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Byte Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Field Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>0x80</para>
</entry>
<entry>
<para>Valid Header</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x01</para>
</entry>
<entry>
<para>VFC Response Format</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x02</para>
</entry>
<entry>
<para>Asynchronous Event</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0x04</para>
</entry>
<entry>
<para>Management Datagram</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>4-7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Summary Status</para>
</entry>
</row>
<row>
<entry>
<para>8-15</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>8 byte command correlator</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_vfc_npiv_req">
<title>VFC and NPIV Requirements</title>
<para>This normative section provides the general requirements for the
support of VFC.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vfc_npiv_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform must implement the
Reliable Command/Response Transport option as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vfc_npiv_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform must implement the
Logical Remote DMA option as defined in
<xref linkend="dbdoclet.50569348_61656" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vfc_npiv_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform must allocate a WWPN
pair for each VFC client and must present the WWPNs to the VFC clients in
their OF device tree
<xref linkend="dbdoclet.50569364_35596" />.</para>
<para>In addition to the firmware primitives, and the structures they
define, the partition&#8217;s OS needs to know specific information
regarding the configuration of the virtual IOA&#8217;s that it has been
assigned so that it can load and configure the correct device driver
code. This information is provided by the OF device tree node associated
with the virtual IOA (see
<xref linkend="dbdoclet.50569364_98316" /> and
<xref linkend="dbdoclet.50569364_23132" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vfc_npiv_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> On P9 Firmware
and newer, the platform must implement the Subordinate CRQ
Transport option as defined in
<xref linkend="dbdoclet.50569348_28179" />.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569364_98316">
<title>Client Partition VFC Device Tree Node</title>
<para>Client partition VFC device tree nodes have associated packages
such as disk-label, deblocker, iso-13346-files and iso-9660-files as well
as children nodes such as block and byte as appropriate to the specific
virtual IOA configuration as would the node for a physical FC IOA.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569364_98316"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform&#8217;s OF device
tree for client partitions must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, a node of name
<emphasis role="bold"><literal>&#8220;vfc-client&#8221;</literal></emphasis> as the parent of a sub-tree
representing the virtual IOAs assigned to the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569364_98316"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vfc-client</literal></emphasis> OF node must contain properties as defined
in
<xref linkend="dbdoclet.50569364_35596" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569364_35596">
<title>Properties of the VFC Node in the Client
Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name, the
value shall be
<emphasis role="bold"><literal>&#8220;vfc-client&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type, the
value shall be
<emphasis role="bold"><literal>&#8220;fcp&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA, the value shall include
<emphasis role="bold"><literal>&#8220;IBM,vfc-client&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form specified in
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of three values
(LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall().</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-1&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property that represents one of two WWPNs assigned to
this VFC client node. This property is a
<emphasis role="bold"><literal>prop-encoded-array</literal></emphasis> each encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. The array consists of the high
order 32 bits and low order 32 bits of the WWPN such that (32
bits high | 32 bits low) is the 64 bit WWPN. The WWPN that the
client is to use (
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-1&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-2&#8221;</literal></emphasis>) is
communicated to the client by the server as part of the
client-server communications protocol.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-2&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property that represents one of two WWPNs assigned to
this VFC client node This property is a
<emphasis role="bold"><literal>prop-encoded-array</literal></emphasis> each encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. The array consists of the high
order 32 bits and low order 32 bits of the WWPN such that (32
bits high | 32 bits low) is the 64 bit WWPN. The WWPN that the
client is to use (
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-1&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,port-wwn-2&#8221;</literal></emphasis>) is
communicated to the client by the server as part of the
client-server communications protocol.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Standard property name that defines the interrupt number(s)
and range(s) handled by this device. Subordinate CRQs
associated with this VFC use interrupt numbers from these
ranges. Only present on P9 Firmware and newer.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569364_98316"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vfc-client</literal></emphasis> node must have as children the appropriate
block (<emphasis role="bold"><literal>disk</literal></emphasis>) and byte (<emphasis role="bold"><literal>tape</literal></emphasis>) nodes.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569364_23132">
<title>Server Partition VFC Device Tree Node</title>
<para>Server partition VFC IOA nodes have no children nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569364_23132"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform&#8217;s OF device
tree for server partitions must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, a node of name
<emphasis role="bold"><literal>&#8220;vfc-server&#8221;</literal></emphasis> as the parent of a sub-tree
representing the virtual IOAs assigned to the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569364_23132"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VFC option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vfc-server</literal></emphasis> node must contain properties as defined in
<xref linkend="dbdoclet.50569364_40283" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569364_40283">
<title>Properties of the VFC Node in the Server
Partition</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="65*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device name, the
value shall be
<emphasis role="bold"><literal>&#8220;vfc-server&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the virtual device type, the
value shall be
<emphasis role="bold"><literal>&#8220;fcp&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the programming models that are
compatible with this virtual IOA, the value shall include
<emphasis role="bold"><literal>&#8220;IBM,vfc-server&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA presented as an
encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. The value shall be of the
form
<xref linkend="dbdoclet.50569341_32742" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />,
specifying the register addresses, used as
the unit address (unit ID), associated with this virtual IOA
presented as an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of two sets (two
window panes) of three values (LIOBN, phys, size) encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>. Of these two triples, the
first describes the window pane used to map server partition
memory, the second is the window pane through which the client
partition maps its memory that it makes available to the server
partition. (Note the mapping between the LIOBN in the second
window pane of a server virtual IOA&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property
and the corresponding client IOA&#8217;s RTCE table is made
when the CRQ successfully completes registration. See
<xref linkend="dbdoclet.50569348_40629" /> for more information
on window panes.)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall()</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vserver&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying that this is a virtual server
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See Definition Column</para>
</entry>
<entry>
<para>Standard property name that defines the interrupt number(s)
and range(s) handled by this device. Subordinate CRQs
associated with this VFC use interrupt numbers from these
ranges. Only present on P9 Firmware and newer.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>&#160;</para>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569366_19541">
<title>Virtual Network Interface Controller (VNIC)</title>
<para>This section defines a Virtual Network Interface Controller (VNIC)
interface to a server partition interfacing to a physical Network Interface
Controller (NIC) adapter that allows multiple partitions to share a
physical port. The implementation support is provided by code running in a
server partition that uses the mechanisms of the Synchronous VIO
Infrastructure (or equivalent thereof as seen by the client) to service I/O
requests for code running in a client partition. The client partition appears to enjoy the services of its own
NIC adapter. The terms server and client partitions refer to platform
partitions that are respectively servers and clients of requests, usually
I/O operations, using the physical NIC that is assigned to the server
partition. This allows a platform to have more client partitions than it
may have physical NICs because the client partitions share I/O adapters via
the server partition.</para>
<para>The VNIC model makes use of Remote DMA which is built upon the
architecture specified in the following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
</itemizedlist>
<para>The use of Remote DMA has implications that the physical NIC be able
to do some of its own vitualization. For example, for an Ethernet adapter,
being able to route receive requests, via DMA to the appropriate client
partition, based on the addressing in the incoming packet.</para>
<section>
<title>VNIC General</title>
<para>This section contains an informative outline of the architectural
intent of the use of VNIC. Other implementations of the server and client
partition code, consistent with this architecture, are possible and may
be preferable.</para>
<para>The client partition provides the virtual equivalent of a single
port NIC adapter via each VNIC client IOA. The platform, through the
partition definition, provides means for defining the set of virtual
IOA&#8217;s owned by each partition and their respective location codes.
The platform also provides, through partition definition, instructions to
connect each client partition&#8217;s VNIC client IOA to a specific
server partition&#8217;s VNIC server IOA. The mechanism for specifying
this partition definition is beyond the scope of this architecture. The
human readable handle associated with the partition definition of virtual
IOAs and their associated interconnection and resource configuration is
the virtual location code. The OF unit address (unit ID) remains the
invariant handle upon which the OS builds its &#8220;physical to
logical&#8221; configuration. The platform also provides a method to
assign unique MAC addresses for each VNIC client adapter. The mechanism
for allocating port names is beyond the scope of this
architecture.</para>
<para>The client partition&#8217;s device tree contains one or more nodes
notifying the partition that it has been assigned one or more virtual
adapters. The node&#8217;s
<emphasis role="bold"><literal>&#8220;type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> properties notify the
partition that the virtual adapter is a VNIC. The unit address of the
node is used by the client partition to map the virtual device(s) to the
OS&#8217;s corresponding logical representations. The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property communicates
the size of the RTCE table window panes that the hypervisor has
allocated. The node also specifies the interrupt source number that has
been assigned to the Reliable Command/Response Transport connection and
the RTCE range that the client partition device driver may use to map its
memory for access by the server partition via Logical Remote DMA. The
client partition, uses the hcall()s associated with the Reliable
Command/Response Transport facility to register and deregister its CRQ,
manage notification of responses, and send command requests to the server
partition. The client partition uses the hcall()s associated with the
Subordinate CRQ Transport facility to register and deregister any
sub-CRQs necessary for the operations of the VNIC.</para>
<para>The client partition, upon noting the device tree entry for the
virtual adapter, loads the device driver associated with the value of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property. The device driver,
when configured and opened, allocates memory for its CRQ (an array, large
enough for all possible responses, of 16 byte elements), pins the queue
and maps it into the I/O space of the RTCE window specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property using the
standard kernel mapping services that subsequently use the H_PUT_TCE
hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next,
I/O request control blocks (within which the I/O requests commands are
built) are allocated, pinned, and mapped into I/O address space. Finally,
the device driver registers to receive control when the interrupt source
specified in the virtual IOA&#8217;s device tree node signals.</para>
<para>Once the CRQ is setup, the device driver in the client queues an
Initialization Command/Response with the second byte of
&#8220;Initialize&#8221; in order to attempt to tell the hosting side
that everything is setup on the hosted side. The response to this send
may be that the send has been dropped or has successfully been sent. If
successful, the sender should expect back an Initialization
Command/Response with a second byte of &#8220;Initialization
Complete,&#8221; at which time the communication path can be deemed to be
open. If dropped, then the sender waits for the receipt of an
Initialization Command/Response with a second byte of
&#8220;Initialize,&#8221; at which time an &#8220;Initialization
Complete&#8221; message is sent, and if that message is sent
successfully, then the communication path can be deemed to be
open.</para>
<para>Once the CRQ connection is complete between the client and the
server, the client receives from the server the number of sub-CRQs that
can be supported on the client side. The client allocates memory for the
first sub-CRQ (an array, large enough for all possible responses, of 32
byte elements), pins the queue and maps it into the I/O space of the RTCE
window specified in the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property using the
standard kernel mapping services that subsequently use the H_PUT_TCE
hcall(). The queue is then registered using the H_REG_SUB_CRQ hcall().
This process continues until all desired sub-CRQs are registered or until
the H_REG_SUB_CRQ hcall() indicates that the resources allocated to the
client for sub-CRQs for the virtual IOA have already been allocated
(H_Resource returned). Interrupt numbers for the Sub-CRQs that have been
registered, are returned by the H_REG_SUB_CRQ hcall() (See
<xref linkend="dbdoclet.50569348_63838" />).</para>
<para>Once all the CRQs and Sub-CRQs are setup, the communications
between the client and server device drivers may commence for purposes of
further setup operations, and then normal I/O requests, error
communications, etc. The protocol for this communications is beyond the
scope of this architecture.</para>
</section>
<section xml:id="sec_vnic_req">
<title>VNIC Requirements</title>
<para>This normative section provides the general requirements for the
support of VNIC.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vnic_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VNIC option:</emphasis> The platform must implement the
Reliable Command/Response Transport option as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vnic_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VNIC option:</emphasis> The platform must implement the
Subordinate CRQ Transport option as defined in
<xref linkend="dbdoclet.50569348_28179" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vnic_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VNIC option:</emphasis> The platform must implement the
Logical Remote DMA option as defined in
<xref linkend="dbdoclet.50569348_61656" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vnic_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VNIC option:</emphasis> The platform&#8217;s OF device
tree for client partitions must include as a child of the
<emphasis role="bold"><literal>/vdevice</literal></emphasis> node, at least one node of name
<emphasis role="bold"><literal>&#8220;vnic&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vnic_req"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VNIC option:</emphasis> The platform&#8217;s
<emphasis role="bold"><literal>vnic</literal></emphasis> OF node must contain properties as defined in
<xref linkend="dbdoclet.50569366_41555" /> (other standard I/O adapter
properties are permissible as appropriate).</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569366_41555">
<title>Properties of the <emphasis role="bold"><literal>vnic</literal></emphasis> Node in the OF Device Tree</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="50*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required for vnic?</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required for vnic-server?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y<?linebreak?>Value = <emphasis role="bold"><literal>&#8220;ibm,vnic&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y<?linebreak?>Value = <emphasis role="bold"><literal>&#8220;ibm,vnic-server&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device name.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>N</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device type, the value shall be
<emphasis role="bold"><literal>&#8220;network&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Property not present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y<?linebreak?>Value includes: <emphasis role="bold"><literal>&#8220;ibm,vnic&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y<?linebreak?>Value includes: <emphasis role="bold"><literal>&#8220;ibm,vnic-server&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
programming models that are compatible with this virtual IOA.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
<entry>
<para>Present if appropriate.</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent
location code associated with this virtual IOA.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the unit
address (unit ID) associated with this virtual IOA presented as
an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y<?linebreak?>Value = a single triplet</para>
</entry>
<entry>
<para>Y<?linebreak?>Value = two triplet</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of one or more sets of three values (triplet)
(LIOBN, phys, size) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>For the vnic-server the two tripples describe two window panes:
the first describes the window pane used to map server partition memory;
the second is the window pane through which the client partition maps
its memory that it makes available to the server partition.
(<emphasis role="bold">Note:</emphasis> the mapping between
the LIOBN in the second window pane of a server virtual IOA’s
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property and the corresponding client IOA’s RTCE table is made when the
CRQ successfully completes registration. See
<xref linkend="dbdoclet.50569348_40629" />.)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall().</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>Present if the platform implements DR for this
node.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that
are used to encode the physical address field of dma-window
properties. This property is present when the dma address
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;local-mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
locally administered MAC addresses are denoted by having the
low order two bits of the high order byte being 0b10.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
initial MAC address (may be changed by a VNIC CRQ
command).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;supported-network-types&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name as per
<emphasis><xref linkend="dbdoclet.50569387_27008" /></emphasis>.
Reports possible types of &#8220;network&#8221;
the device can support.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;chosen-network-type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name as per
<emphasis><xref linkend="dbdoclet.50569387_27008" /></emphasis>.
Reports the type of &#8220;network&#8221; this
device is supporting.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;max-frame-size&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, to indicate maximum
packet size.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;address-bits&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, to indicate network
address length.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name that defines the interrupt
number(s) and range(s) handled by this device. Subordinate CRQs
associated with this VNIC use interrupt numbers from these
ranges.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,vf-loc-code&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Vendor unique property name to define the physical device
virtual function upon which the vnic-server runs. The value is
that of the <emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
property of the physical device virtual function.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,vnic-mode&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Vendor unique property that represents the operational
mode in which the vnic-server runs.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,vnic-client-mac&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Vendor unique property that represents a vNIC server's client MAC address.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section xml:id="sec_virtual_trusted_platform_module">
<title>Virtual Trusted Platform Module (VTPM)</title>
<para>This section defines the Virtual Trusted Platform Module (VTPM) option.
Firmware can provide the service of a VTPM device to a partition using the
mechanisms of the Reliable Command/Response Transport and Logical Remote DMA
of the Synchronous VIO Infrastructure. A VTPM device primarily allows VTPM
aware system firmware and operating systems to perform a trusted boot.</para>
<para>The VTPM architecture is built upon the architecture specified in the
following sections:</para>
<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569348_21877" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_94955" /></para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569348_51946" /></para>
</listitem>
<!--listitem>
<para><xref linkend="sec_partition_adjunct_option" /></para>
</listitem-->
</itemizedlist>
<section xml:id="sec_vtpm_general">
<title>VTPM General</title>
<para>This informative section provides an outline of the architectural intent
of the use of the VTPM.</para>
<para>The platform, through the partition definition can define multiple VTPMs,
and ensures that only a single VTPM is associated with a partition.</para>
<para>The client partition may be assigned various virtual adapters, each with
a corresponding node in the device tree. The node's
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
properties may be used to distinguish between adapter types and thus locate a
VTPM. The node's unit address is an invariant handle to the
adapter and given by the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.
The <emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property encodes the adapter's LIOBN and RTCE table size for use with the
CRQ and LDRMA mechanisms. The CRQ's assigned interrupt source number is given
by the node's
<emphasis role="bold"><literal>&#8220;interrupt&#8221;</literal></emphasis> property.</para>
<para>The presence of a VTPM device tree node causes the client to load a
device driver associated with the node's
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property.
The driver first allocates and pins memory for the CRQ - an array of
16 byte elements, large enough to contain all possible responses.
The queue is then RTCE mapped using the H_PUT_TCE hcall and the values of the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property.
The CRQ is registered via the H_REG_CRQ hcall,
and the partition may request interrupt notification using the source given by the
<emphasis role="bold"><literal>&#8220;interrupt&#8221;</literal></emphasis> property.</para>
<para>The driver then follows the VTPM initialization steps as described in
<xref linkend="sec_virtual_trusted_platform_module" />
resulting in the allocation and RTCE mapping of memory buffers with which to send/receive TPM commands and responses of the format described in the Trusted Computing Group TPM Specification, version 1.2 [29]. Once initialized the client may send commands by writing them directly to the RTCE-mapped memory buffer and issuing the H_SEND_CRQ hcall with the buffer's I/O address. If successful, the driver awaits an interrupt indicating that a response to the command is available – and is present in the same buffer used for command transmission. Notice that the client does not use LRDMA facilities itself, firmware is the only entity to copy data.
</para>
</section>
<section xml:id="sec_vtpm_requirements">
<title>VTPM Requirements</title>
<para>This normative section provides the general requirements for the support of VTPM.</para>
<variablelist>
<!--varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vtpm_requirements"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VTPM option:</emphasis> The platform
must implement the Partition Adjunct Option as defined in
<xref linkend="sec_partition_adjunct_option" />.</para>
</listitem>
</varlistentry-->
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vtpm_requirements"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VTPM option:</emphasis> The platform must implement the
Reliable Command/Response Transport option as defined in
<xref linkend="dbdoclet.50569348_48491" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_vtpm_requirements"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the VTPM option:</emphasis> The platform must implement the
Logical Remote DMA option as defined in
<xref linkend="dbdoclet.50569348_61656" />.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In addition to the firmware primitives, and the structures they define,
the partition’s OS needs to know specific information regarding the configuration
of the virtual IOA’s that it has been assigned so that it can load and configure
the correct device driver code. This information is provided by the OF device
tree node associated with the virtual IOA
(<xref linkend="table_properties_vtpm_node"/>).</para>
<table frame="all" pgwide="1" xml:id="table_properties_vtpm_node">
<title>Properties of the <emphasis role="bold"><literal>vtpm</literal></emphasis> Node in the OF Device Tree</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="55*" />
<thead valign="middle">
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device name, the value shall be
<emphasis role="bold"><literal>&#8220;vtpm&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
virtual device type, the value shall be
<emphasis role="bold"><literal>&#8220;IBM,vtpm&#8221;</literal></emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the
programming models that are compatible with this virtual IOA, the value shall be either
<emphasis role="bold"><literal>&#8220;IBM,vtpm&#8221;</literal></emphasis>
for VTPM version 1.2 or
<emphasis role="bold"><literal>&#8220;IBM,vtpm20&#8221;</literal></emphasis>
for VTPM version 2.0.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name per
<xref linkend="dbdoclet.50569387_45524" />, specifying the unit
address (unit ID) associated with this virtual IOA presented as
an encoded array as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> of length
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value shall be
0xwhatever (virtual
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property used for unit
address no actual locations used, therefore, the size field has
zero cells (does not exist) as determined by the value of the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Standard property name specifying the interrupt source
number and sense code associated with this virtual IOA
presented as an encoded array of two cells encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with the first cell containing
the interrupt source number, and the second cell containing the
sense code 0 indicating positive edge triggered. The interrupt
source number being the value returned by the H_XIRR or H_IPOLL
hcall().</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Device's phandle encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis> –
present only if DRC is enabled..</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For DR</para>
</entry>
<entry>
<para>The integer index for the connector between the device and
its parent – present only if DRC is enabled.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
format. The property value specifies the number of cells that are used
to encode the physical address field of dma-window properties. This
property is present when the dma address format cannot be derived
using the method described in the definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>See definition column</para>
</entry>
<entry>
<para>Property name, to define the package&#8217;s dma address
size format. The property value specifies the number of cells
that are used to encode the size field of dma-window
properties. This property is present when the dma address size
format cannot be derived using the method described in the
definition for the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property
in
<xref linkend="dbdoclet.50569368_91814" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the DMA window associated with
this virtual IOA presented as an encoded array of three values
(LIOBN, phys, size).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Property name specifying the unique and persistent location
code associated with this virtual IOA.</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold"><literal>&#8220;ibm,adjunct-virtual-addresses&#8221;</literal></emphasis></para>
</entry>
<entry>
<para>Y</para>
</entry>
<entry>
<para>Vendor unique property name indicating ranges of the client program virtual address space that are used by the virtual device serving partition adjunct.
See <xref linkend="dbdoclet.50569368_26956" /> information about the children
of the <literal>/vdevice</literal> node.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
</chapter>
Reference in New Issue View Git Blame Copy Permalink