Linux-Architecture-Reference/Virtualization/ch_virtual_io.xml

<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="LoPAR.Platform" />. 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="LoPAR.Platform" />)</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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" /> 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="LoPAR.Platform" />.
              </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="LoPAR.DeviceTree" /> 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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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 */
      );]]></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>
          </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>Verifies the VLAN number -- else H_Parameter.</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>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>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.</para>
            </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 R1–17.3.6.2.2–3 is not required.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>47</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>48</para>
                </entry>
                <entry>
                  <para>Large Send Indication Supported</para>
                </entry>
                <entry>
                  <para>The bit is implemented when the large send indication bit in
                  the I/O descriptor passed to H_SEND_LOGICAL_LAN is
                  supported by firmware.</para>
                  <para>0: Software must not request large send indication,
                  by setting Bit 5 of the buffer descriptor.</para>
                  <para>1: Software may request large send indication, by
                  setting Bit 5 of the buffer descriptor.</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.</para>
                  <para>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.</para>
                  <para>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>
              <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 Indication 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>
                </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.</para>
              </listitem>
           	</varlistentry>
          </variablelist>
        </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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.Platform" />.</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="LoPAR.Platform" />.</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>

  <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="LoPAR.Platform" /> information on
                Virtual Card Connector Location Codes.</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="LoPAR.DeviceTree" /> section on System Bindings.</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="LoPAR.DeviceTree" /> section on System Bindings.</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="50%" ?><?dbfo table-width="50%" ?>
        <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-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-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-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>
      </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 - 13:5</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>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>

    <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="LoPAR.Platform" /> information on
                Virtual Card Connector Location Codes.</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>Reserved</para>
                  </entry>
                  <entry>
                    <para>0x6-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_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>
              </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>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>
      </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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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>
                  </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="LoPAR.Platform" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" />.</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="LoPAR.DeviceTree" /> information about the children
                  of the <literal>/vdevice</literal> node.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

    </section>
  </section>
</chapter>