Linux-Architecture-Reference/RTAS/sec_rtas_get_indices.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright (c) 2016 OpenPOWER Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xl="http://www.w3.org/1999/xlink"
         version="5.0"
         xml:lang="en"
         xml:id="sec_get_indices_rtas_call">

    <title><emphasis>ibm,get-indices</emphasis> Call</title>

    <para>The RTAS function
    <emphasis>ibm,get-indices</emphasis> is used to obtain the indices and
    location codes for a specified indicator or sensor token. It allows for
    obtaining the list of indicators and sensors dynamically and therefore
    assists in any Dynamic Reconfiguration operation that involves indicators
    and sensors being added or deleted from the platform (unlike the
    <emphasis role="bold"><literal>/rtas</literal></emphasis> node
    <emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
    <emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
    and <emphasis role="bold"><literal>&#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).
    This call also allows discontiguous indices for a particular indicator or
    sensor type (unlike the
    <emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis>,
    <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis>, and
    <emphasis role="bold"><literal>
    &#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).</para>
    <para>This RTAS call is not used for DR indicators (9001, 9002, and 9003)
    or DR sensors (9003). See the following sections in the DR chapter for more
    information:
    <xref linkend="LoPAR.Virtualization" /> and
    <xref linkend="LoPAR.Virtualization" />.</para>
    <para>It may require several calls to the
    <emphasis>ibm,get-indices</emphasis> RTAS routine to get the entire list of
    indicators or sensors of a particular type. Each call may specify a
    different work area.</para>
    <para>The OS may not interleave calls to
    <emphasis>ibm,get-indices</emphasis> for different indicator or sensor
    types. Other standard RTAS locking rules apply.</para>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For all DR options:</emphasis> The RTAS function
            <emphasis>ibm,get-indices</emphasis> must implement the argument call buffer
            defined by
            <xref linkend="dbdoclet.50569332_50675" />.</para>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_50675">
              <title>Argument Call Buffer
              <emphasis>ibm,get-indices</emphasis></title>
              <tgroup cols="3">
                <colspec colname="c1" colwidth="1*" />
                <colspec colname="c2" colwidth="2*" />
                <colspec colname="c3" colwidth="4*" />
                <thead>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">Parameter Type</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Name</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Values</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry morerows="7" valign="middle">
                      <para>In</para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis>Token</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Token for
                      <emphasis>ibm,get-indices</emphasis></para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Number Inputs</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>5</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Number Outputs</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>2</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Indicator or Sensor</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>0: indicator of given type</para>
                      <para>1: sensor of given type</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Indicator Type</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Indicator or sensor type (for example, 9006, 9007)</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Work Area Address</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Address of work area</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Work Area Size</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Size of work area</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Starting Number</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Integer representing first indicator number to
                      return</para>
                    </entry>
                  </row>
                  <row>
                    <entry morerows="1" valign="middle">
                      <para>Out</para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis>Status</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>-1: Hardware error</para>
                      <para>-3: Indicator type not supported</para>
                      <para>-4: Optional: Indicator list changed, start again</para>
                      <para>0: Success</para>
                      <para>1: More data available; call again</para>
                      <para>990x:Extended Delay where x is a number 0-5 (see text
                      below)</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Next Starting Number</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Integer to use as the Starting Number parameter on the next
                      call, or 1 if no more calls are required</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>When the 990x
            <emphasis>Status</emphasis> is returned, it is suggested that software delay
            for 10 raised to the x milliseconds (where x is the last digit of the 990x
            return code), before calling
            <emphasis>ibm,get-indices</emphasis> with the same Starting Number and
            Indicator Type. However, software may issue the
            <emphasis>ibm,get-indices</emphasis> call again either earlier or later than
            this.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para>The OS must not interleave calls to
            <emphasis>ibm,get-indices</emphasis> for different indicator or sensor
            types.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para>On the first call to get a particular
            <emphasis>Indicator Type</emphasis>, the caller must provide a Starting
            Number of 1 (32-bit integer)</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para>When
            <emphasis>ibm,get-indices</emphasis> is called with a Starting Number of 1,
            firmware must refresh any stale data in previously cached firmware buffers
            for that indicator (for example, data made stale by a Dynamic
            Reconfiguration operation).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para>When calling
            <emphasis>ibm,get-indices</emphasis> with a Starting Number of 1, a
            previously returned
            <emphasis>Next Starting Number</emphasis> value must be discarded.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para>Optionally, if firmware detects a change in
            the indicator list before the entire list is returned, the
            <emphasis>ibm,get-indices</emphasis> call must return a -4 and the caller
            must start again with a Starting Number of 1.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para>The return data format in the work area for
            all sensors and indicators must be as follows:</para>

            <itemizedlist>
              <listitem>
                <para>Number Returned: 32-bit integer representing the number of
                indicator indices returned on this call</para>
              </listitem>

              <listitem>
                <para>Sets of (32-bit integer index, 32-bit integer length of location
                code including NULLs, location code string (NULL terminated and padded to
                nearest 4 byte boundary)), one set per indicator or sensor, with the number
                of sets indicated by the first integer in this work buffer</para>
              </listitem>
            </itemizedlist>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para>If the
            <emphasis>Status</emphasis> returned is 1 (more data available, call again),
            then the caller must call
            <emphasis>ibm,get-indices</emphasis> again with the
            <emphasis>Starting Number</emphasis> parameter set to the Next Starting
            Number integer from the previously returned buffer.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
          <listitem>
            <para>The <emphasis>ibm,get-indices</emphasis> RTAS call must return the
            <emphasis>Status</emphasis> value of -3 for the following conditions:</para>

            <orderedlist numeration="loweralpha">
              <listitem>
                <para>Indicator type not supported</para>
              </listitem>

              <listitem>
                <para>No indicators of specified Indicator Type available to
                caller</para>
              </listitem>
            </orderedlist>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
          <listitem>
            <para>If the <emphasis>ibm,get-indices</emphasis> RTAS call returns a
            <emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
            caller must consider that the contents of the work area is not
            defined.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
          <listitem>
            <para>The work area specified in the
            <emphasis>ibm,get-indices</emphasis> RTAS call argument buffer must be
            contiguous in logical real memory and must reside below 4GB.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
          <listitem>
            <para>The <emphasis>ibm,get-indices</emphasis> RTAS call must only return the
            indicator or sensor indices to which the caller has authorized access at
            the time of the call.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
          <listitem>
            <para>The <emphasis>ibm,get-indices</emphasis> RTAS call must make no assumptions
            about the contents of the work area on the beginning of the call.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
          <listitem>
            <para>When the platform supports the
            <emphasis>ibm,get-indices</emphasis> RTAS call, the device tree must include
            the
            <emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property
            in the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting
            indicator information and must include the
            <emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property in
            the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting sensor
            information.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
          <listitem>
            <para>When an indicator token is provided in the
            <emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property,
            it must not be included in the
            <emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
            property and must not be included in the
            <emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> property.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
          <listitem>
            <para>When a sensor token is provided in the
            <emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property, it
            must not be included in the
            <emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
            property and must not be included in the
            <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
          <listitem>
            <para>When an environmental sensor token is
            provided in the
            <emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property,
            users of data in the
            <emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis> property for
            that sensor token must not assume that the indices are contiguous for that
            sensor token (that is, any of the indices between 0 and the maxindex,
            inclusive, may be missing).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569332_80480">
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
          <listitem>
            <para>When the value of
            any index returned is 0xFFFFFFFF, the OS must use the
            <emphasis>ibm,get-dynamic-sensor-state</emphasis> and
            <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS functions for this
            sensor or indicator, using the location code to identify the sensor or
            indicator.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
        xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
          <listitem>
            <para>The OS must not call
            <emphasis>get-sensor-state</emphasis> or
            <emphasis>get-indicator</emphasis> with an index value of 0xFFFFFFFF.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

    <section xml:id="dbdoclet.50569332_30542">
      <title><emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call</title>

      <para>This RTAS call behaves as the RTAS
      <emphasis>set-indicator</emphasis> call, except that the instance of the
      indicator is identified by a location code instead of a index.</para>

      <variablelist>
       	<varlistentry xml:id="dbdoclet.50569332_58519">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>Platforms that
              implement any indicators that are identified by location code instead of
              index (see Requirement
              <xref linkend="dbdoclet.50569332_80480" />) must implement the
              <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS function.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para>The RTAS function
              <emphasis>ibm,set-dynamic-indicator</emphasis> must implement the argument
              call buffer defined by
              <xref linkend="dbdoclet.50569332_14870" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14870">
                <title>Argument Call Buffer
                <emphasis>ibm,set-dynamic-indicator</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">
                            <emphasis>Name</emphasis>
                          </emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="5" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,set-dynamic-indicator</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>3</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Indicator</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token defining the indicator</para>
                        <para>9006: Error Log</para>
                        <para>9007: Identify Indicator</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>State</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Desired new state; see
                        <xref linkend="dbdoclet.50569332_32237" />.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Location Code Address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real or Logical address of a location code string, in the
                        format defined by Requirement
                        <xref linkend="dbdoclet.50569332_69341" /></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware error</para>
                        <para>-2: Busy, try again later</para>
                        <para>-3: No such indicator</para>
                        <para>0: Success</para>
                        <para>990x: Extended delay, where x is a number between 0 and
                        5, as described below</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <para>When 990x
              <emphasis>Status</emphasis> is returned, it is suggested that software
              delay for 10 raised to the power
              <emphasis>x</emphasis> milliseconds (where
              <emphasis>x</emphasis> is the last digit of the 990x return code), before
              calling
              <emphasis>ibm,set-dynamic-indicator</emphasis> with the same indicator
              type and location code. However, software may call
              <emphasis>ibm,set-dynamic-indicator</emphasis> again either earlier or
              later than this.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>The OS must not call
              <emphasis>ibm,set-dynamic-indicator</emphasis> with a different indicator
              until a non-busy return
              <emphasis>Status</emphasis> has been received from the previous
              <emphasis>ibm,set-dynamic-indicator</emphasis> call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para>The location code string referenced by the
              <emphasis>Location Code Address</emphasis> argument in the
              <emphasis>ibm,set-dynamic-indicator</emphasis> argument call buffer must
              reside in contiguous in real memory below an address of 4GB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569332_69341">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>The input data
              format in the work area must be as follows:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>32-bit integer length of the location code string, including
                  NULL</para>
                </listitem>

                <listitem>
                  <para>Location code string, NULL terminated, identifying the sensor to
                  be set.</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para>The platform must not modify the location
              code string.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para>The OS must only use this call for
              indicators which have been provided by the
              <emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
              0xFFFFFFFF.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para>Platforms must identify all indicators
              except types 9006 and 9007 by index.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para>The <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS call must return A
              <emphasis>Status</emphasis> of -3 for the following conditions:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>Indicator type not supported</para>
                </listitem>

                <listitem>
                  <para>The specified location code does not identify a valid
                  indicator</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_61055">
      <title><emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call</title>
      <para>This RTAS call behaves as the RTAS
      <emphasis>get-sensor-state</emphasis> call, except that the instance of
      the sensor is identified by a location code instead of a index.</para>

      <variablelist>
       	<varlistentry xml:id="dbdoclet.50569332_54151">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>Platforms that
              implement any sensors that are identified by location code instead of
              index (see Requirement
              <xref linkend="dbdoclet.50569332_80480" />) must implement the
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS function.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para>The RTAS function
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> must implement the
              argument call buffer defined by
              <xref linkend="dbdoclet.50569332_71500" />.</para>
              <para>&#160;</para>
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71500">
                <title>Argument Call Buffer
                <emphasis>ibm,get-dynamic-sensor-state</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,get-dynamic-sensor-state</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Sensor</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token defining the sensor</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Location Code Address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real or Logical address of a location code string, in the
                        format defined by Requirement
                        <xref linkend="dbdoclet.50569332_75857" /></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware error</para>
                        <para>-2: Busy, try again later</para>
                        <para>-3: No such indicator</para>
                        <para>0: Success</para>
                        <para>990x: Extended delay, where x is a number between 0 and
                        5, as described below</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>State</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Current state of the sensor as defined in the
                        <emphasis>Defined Values</emphasis> column of
                        <xref linkend="dbdoclet.50569332_23534" />.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <para>When 990x
              <emphasis>Status</emphasis> is returned, it is suggested that software
              delay for 10 raised to the power
              <emphasis>x</emphasis> milliseconds (where
              <emphasis>x</emphasis> is the last digit of the 990x return code), before
              calling
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> with the same indicator
              type and location code. However, software may call
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> again either earlier or
              later than this.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>The OS must not call
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> with a different sensor
              until a non-busy return
              <emphasis>Status</emphasis> has been received from the previous
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para>The work area must be contiguous in real
              memory and must reside below 4GB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569332_75857">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>The input data
              format in the work area must be as follows:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>32-bit integer length of the location code string, including
                  NULL</para>
                </listitem>

                <listitem>
                  <para>Location code string, NULL terminated, identifying the sensor to
                  be set.</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para>The platform must not modify the location
              code string.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para>The OS must only use this call with sensors
              which have been provided by the
              <emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
              0xFFFFFFFF.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para>The platform must use the
              <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS call only for
              dynamic sensor types of 9004, 9006 and 9007.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para>A <emphasis>Status</emphasis> of -3 must be returned for the following
              conditions:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>Sensor type not supported</para>
                </listitem>

                <listitem>
                  <para>The specified location code does not identify a valid
                  sensor</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_72964">
      <title><emphasis>ibm,get-vpd</emphasis> RTAS Call</title>
      <para>This RTAS call allows for collection of VPD that changes after OS
      boot time (after the initial reporting in the OF device tree). When this
      call is implemented, there is no overlap between what is reported in the
      device tree and what is reported with this RTAS call. Also, when this
      RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
      is dynamically changed during OS run time is reported with this call and
      not via the
      <emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property in the OF device
      tree.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>For all Dynamic Reconfiguration options
              except PCI Hot Plug, when the platform VPD can change dynamically due to
              a Dynamic Reconfiguration operation, the platform must implement the
              <emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para>The RTAS function
              <emphasis>ibm,get-vpd</emphasis> must implement the argument call buffer
              defined by
              <xref linkend="dbdoclet.50569332_62393" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62393">
                <title>Argument Call Buffer
                <emphasis>ibm,get-vpd</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="6" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,get-vpd</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>4</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>3</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Pointer to Location Code</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real address of NULL-terminated string, contiguous in
                        real memory and below 4GB, which is the location code of the
                        FRU for which to obtain the VPD. When this parameter references
                        a NULL string the VPD for all location codes is
                        returned.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Address of work area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Size</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Size of work area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Sequence Number</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Integer representing the sequence number of the call.
                        First call in sequence starts with 1, following calls (if
                        necessary) use the
                        <emphasis>Next Sequence Number</emphasis> returned from the
                        previous call.</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="2" valign="middle">
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware error</para>
                        <para>-3: Parameter error</para>
                        <para>-4: Optional: VPD changed, start again</para>
                        <para>0: Success</para>
                        <para>1: More data available; call again</para>
                        <para>990x: Extended Delay where x is a number 0-5 (see text
                        below)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Next Sequence Number</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Return this integer as the
                        <emphasis>Sequence Number</emphasis> parameter on the next call
                        to continue the sequence, or 1 if no more calls are
                        required</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Bytes Returned</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Integer representing the number of valid bytes returned
                        in the work area.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <para>When the 990x
              <emphasis>Status</emphasis> is returned, it is suggested that software
              delay for 10 raised to the x milliseconds (where x is the last digit of
              the 990x return code), before calling
              <emphasis>ibm,get-vpd</emphasis> with the same input parameters. However,
              software may issue the
              <emphasis>ibm,get-vpd</emphasis> call again either earlier or later than
              this.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>On the first call to
              <emphasis>ibm,get-vpd</emphasis> for a particular VPD gathering operation,
              the caller must provide a
              <emphasis>Sequence Number</emphasis> of 1 (32-bit integer)</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para>Upon calling
              <emphasis>ibm,get-vpd</emphasis> with a
              <emphasis>Sequence Number</emphasis> of 1, a previously returned
              <emphasis>Next Sequence Number</emphasis> must be discarded. This means
              that multiple calls to
              <emphasis>ibm,get-vpd</emphasis> cannot be interleaved by multiple
              processors, and if processor &#8220;B&#8221; starts a new
              <emphasis>ibm,get-vpd</emphasis> sequence while processor &#8220;A&#8221;
              has a call sequence in process (that is, the function on processor
              &#8220;A&#8221; has returned a
              <emphasis>Status</emphasis> of 1, and the subsequent call has not yet been
              made) then the call sequence on processor &#8220;A&#8221; is
              abandoned.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>Optionally, if firmware detects a change in
              the VPD being requested before the entire VPD is returned, the
              <emphasis>ibm,get-vpd</emphasis> call must return a
              <emphasis>Status</emphasis> of -4 and the caller must start again with a
              Starting Number of 1.</para>
              <para>
              <emphasis role="bold">Implementation Note:</emphasis> The platform should not impede
              forward progress by continuously returning a
              <emphasis>Status</emphasis> of -4.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para>The return data format in the work area
              must be such that after returning all the data and concatenating all data
              together in the order received, that the data is the same as is obtained
              from the
              <emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property of the OF device
              tree.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para>Each stanza of the returned data must
              include the YL (location code) keyword.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para>If the
              <emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then the
              platform must not provide the
              <emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> or
              <emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> properties in the OF
              device tree
              <emphasis>root</emphasis> node.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para>If the
              <emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then any VPD
              which may change after OS boot must be reported via the
              <emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para>If the
              <emphasis>Status</emphasis> returned is 1 (more data available, call
              again), then the caller must call
              <emphasis>ibm,get-vpd</emphasis> again with the
              <emphasis>Sequence Number</emphasis> parameter set to the
              <emphasis>Next Sequence Number</emphasis> integer from the previously
              returned call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para>If a
              <emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
              contents of the work area is not defined.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para>The work area must be contiguous in real
              memory and must reside below 4GB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para>Firmware cannot count on the contents of
              the work area at the beginning of any call to
              <emphasis>ibm,get-vpd</emphasis> (regardless of the value of the
              <emphasis>Sequence Number</emphasis>).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
            <listitem>
              <para>The location code referenced by the
              <emphasis>Pointer to Location Code</emphasis> parameter must reside in
              contiguous real memory below an address of 4GB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
          xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
            <listitem>
              <para>If the
              <emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then firmware
              must supply the
              <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property in the
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node, the value of which is a single cell,
              encoded as with
              <emphasis>encode-int</emphasis>, which is the estimated maximum size in
              bytes of the VPD that is returned if the
              <emphasis>Pointer to Location Code</emphasis> parameter to the
              <emphasis>ibm,get-vpd</emphasis> RTAS function is NULL (that is, all
              system VPD). This size should take in to account possible concurrent
              addition of new platform elements after the partition is started. If
              firmware is unable to estimate this size, it may return a value of 0x0 to
              indicate that no estimate is available.</para>
              <para>
                <emphasis role="bold">Software Implementation Notes:</emphasis>
              </para>

              <orderedlist>
                <listitem>
                  <para>An OS should be prepared for older versions of firmware where
                  the
                  <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property is not
                  provided.</para>
                </listitem>

                <listitem>
                  <para>Each stanza of the returned data must include the YL (location
                  code) keyword.</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_28221">
      <title>Managing Storage Preservation</title>

      <para>Platforms may optionally preserve selected regions of storage
      (LMBs) across client program boot cycles.
      <xref linkend="LoPAR.Platform" /> for more information.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
              must implement the
              <emphasis>ibm,manage-storage-preservation</emphasis> RTAS argument call
              buffer as defined by
              <xref linkend="dbdoclet.50569332_95221" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_95221">
                <title><emphasis>ibm,manage-storage-preservation</emphasis> Argument Call
                Buffer</title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="33*" />
                  <colspec colname="c2" colwidth="33*" />
                  <colspec colname="c3" colwidth="33*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="5" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,manage-storage-preservation</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>3</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Subfunction</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>0 = unused (return -3)</para>
                        <para>1 = Register specified LMB for preservation</para>
                        <para>2 = Query preservation state of specified LMB</para>
                        <para>3 = Deregister for preservation Specific LMB</para>
                        <para>4 = Deregister for preservation all caller&#8217;s
                        LMBs.</para>
                        <para>All other values reserved (return -3)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Reg High</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>The high order 32 bits of the LMB's
                        <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
                        1-3)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Reg Low</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>The low order 32 bits of the LMB's
                        <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
                        1-3)</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1" valign="middle">
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware error</para>
                        <para>-2: Busy</para>
                        <para>-3: Parameter error (Subfunction or Reg invalid; or Reg
                        for a non-preservable LMB)</para>
                        <para>0: Success</para>
                        <para>990x: Extended delay where x is a number 0-5</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Preservation state</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>If
                        <emphasis>Status</emphasis>= Success, the current preservation
                        state of specified LMB (Subfunctions 1-3)</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
              must include the
              <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property in the
              <emphasis>/memory</emphasis> nodes of its OF device tree, containing a
              value which reflects the platform's ability to preserve the specific
              LMB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The value of the
              <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
              LMB must be 0 (cannot be preserved).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
              must not preserve the first LMB, thus must indicate a value of 0 for the
              <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
              LMB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
              must include the
              <emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property in the
              <emphasis>/memory</emphasis> nodes of its OF device tree, valued to
              reflect the platform's preservation state of the specific LMB.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
              a reboot, must include in the OF
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node the
              <emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis> property if the
              previous client program registered one or more of its LMBs for
              preservation.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> If the client
              program registered an LMB for preservation, the platform must preserve
              the LMB's storage state across client program reboots.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
              a reboot, must include in the OF
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node the
              <emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis> property
              which reflects the value of the partition shutdown configuration
              variable, and if this property is not present, a value of 0 must be
              assumed by the OS.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_26596">
      <title><emphasis>ibm,lpar-perftools</emphasis> RTAS Call</title>

      <para>This RTAS call provides access to platform-level facilities for
      performance tools running in a partition on an LPAR system. Platforms may
      require platform-specific tools, beyond the scope of this architecture,
      to make this call available.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool Support option:</emphasis> The platform
              must implement the LPAR option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool Support option:</emphasis> RTAS must
              implement the
              <emphasis>ibm,lpar-perftools</emphasis> call using the argument call
              buffer defined by
              <xref linkend="dbdoclet.50569332_48993" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_48993">
                <title>Argument Call Buffer
                <emphasis>ibm,lpar-perftools</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="7" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,lpar-perftools</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>5</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Subfunction</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1: Convert hypervisor IAR value to method name.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Address High</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Most significant 32 bits of real address of work
                        area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Address Low</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Least significant 32 bits of real address of work
                        area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Size</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Size of work area in bytes</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Sequence Number</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Integer representing the sequence number of this call.
                        First call in sequence starts with 1, following calls (if
                        necessary) use the
                        <emphasis>Next Sequence Number</emphasis> returned from the
                        previous call.</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1" valign="middle">
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy</para>
                        <para>-3: Parameter Error (Subfunction invalid, invalid work
                        area address, invalid work area size)</para>
                        <para>-9002: Partition does not have authority to perform this
                        function</para>
                        <para>-5: Buffer was too small to supply requested data</para>
                        <para>0: Success</para>
                        <para>990x: Extended delay</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Next Sequence Number</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Return this integer as the
                        <emphasis>Sequence Number</emphasis> parameter on the next call,
                        or 1 if no more calls are required.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <para>When 990x
              <emphasis>Status</emphasis> is returned, it is suggested that software
              delay for 10 raised to the x milliseconds (where x is the last digit of
              the 990x return code), before calling the
              <emphasis>ibm,lpar-perftools</emphasis> call with the same input
              parameters. However, software may issue the
              <emphasis>ibm,lpar-perftools</emphasis> call again earlier or later than
              this.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool Support option:</emphasis> For
              <emphasis>subfunction</emphasis> value 1, on input the first 8 bytes of
              the work area must contain the hypervisor IAR address to be converted. On
              output, the first 8 bytes of the work area contain the offset of this
              address from the start of the hypervisor function, method or module,
              followed by a NULL-terminated text string containing the name of the
              hypervisor function, method or module. If the address is not a valid
              address in the hypervisor, on output the buffer must contain 0x0 (8
              bytes) followed by a NULL-terminated text string indicating that the
              address was not valid.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool support option:</emphasis> The work
              area must reside in contiguous memory.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool Support option:</emphasis> If a
              <emphasis>Status</emphasis> of anything other than 0 is returned, the
              contents of the work area are not defined.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Performance Tool Support option:</emphasis> A partition
              must have at most one call to this function in process at a given time.
              This means that if one processor in the partition initiates this call,
              receives a Busy or Extended Delay return, and then another processor
              calls this function with a sequence number of 1, a subsequent call using
              the
              <emphasis>Next Sequence Number</emphasis> returned to the first processor
              results in a Parameter Error return code.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_45918">
      <title><emphasis>ibm,suspend-me</emphasis> RTAS Call</title>
      <para>The
      <emphasis>ibm,suspend-me</emphasis> RTAS call provides the calling OS the
      ability to suspend processing. Suspension of processing is required as
      part of OS hibernation or migration to another platform. This RTAS call
      is made by the last active processor thread of a partition. The OS uses
      the H_JOIN hcall() (see
      <xref linkend="LoPAR.Virtualization" />) to deactivate other
      processing threads. Processing treads may exit H_JOIN due to an
      unmaskable interrupt; if a thread has exited H_JOIN,
      <emphasis>ibm,suspend-me</emphasis> fails with a status of &#8220;multiple
      processor threads active&#8221;. The wake up from suspension is triggered
      by partition state change (see
      <xref linkend="LoPAR.Virtualization" /> sections on "Partition Migration"
      and "Partition Hibernation"). The
      <emphasis>ibm,suspend-me</emphasis> RTAS call returns only on the calling
      virtual processor. Other virtual processors that were inactive when
      <emphasis>ibm,suspend-me</emphasis> was called remain so until they are
      proded by the OS.</para>
      <para>While the logical configuration of a suspended partition remains
      static, the physical properties may change; the OS may wish to issue
      <emphasis>ibm,update-nodes</emphasis> (see
      <emphasis>
      <xref linkend="dbdoclet.50569332_84414" />) to determine if any device
      tree nodes changed, and then</emphasis> refresh its view of the device
      tree physical properties using
      <emphasis>ibm,update-properties</emphasis> (see
      <xref linkend="dbdoclet.50569332_40069" />) and/or
      <emphasis>ibm,configure-connector</emphasis> (see
      <xref linkend="LoPAR.Virtualization" />). Also during suspension, some
      system parameters may have changed. See
      <xref linkend="dbdoclet.50569332_10519" />, for details. The OS may want
      to re-scan selected system parameters.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must implement the Logical Partitioning option (see
              <xref linkend="LoPAR.Virtualization" />)
              <emphasis>.</emphasis></para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> RTAS must
              implement the
              <emphasis>ibm,suspend-me</emphasis> call within a logical partition using
              the argument call buffer defined by
              <xref linkend="dbdoclet.50569332_91600" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_91600">
                <title>Argument Call Buffer
                <emphasis>ibm,suspend-me</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="2" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,suspend-me</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>0</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>9000: Suspension Aborted</para>
                        <para>0: Success -- expected return on function resume</para>
                        <para>-1: Hardware Error</para>
                        <para>&#160;</para>
                        <para>-9004: Partition not suspendable</para>
                        <para>-9005: Multiple processor threads active</para>
                        <para>-9006: Outstanding COP Operations</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
              <emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
              calling partition is in the &#8220;suspendable state&#8221;, else return
              a status of -9004 &#8220;Partition not suspendable&#8221;.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
              <emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
              calling partition has no other active processor thread, else return a
              status of -9005 &#8220;Multiple processor threads active&#8221;.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must implement the Thread Join option (see
              <xref linkend="LoPAR.Virtualization" />).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must restore all partition state as of the time of the call to
              <emphasis>ibm,suspend-me</emphasis> prior to returning from the
              <emphasis>ibm,suspend-me</emphasis> RTAS call, except for the values of
              those Open Firmware Device tree properties as reported using the Update
              OF Tree option, and the system parameters given in
              <xref linkend="dbdoclet.50569332_10519" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must be prepared to respond to OS requests for updated device tree
              information immediately after returning from the
              <emphasis>ibm,suspend-me</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must support the &#8220;update OF tree&#8221; option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must support the &#8220;Partner partition suspended&#8221; CRQ Transport
              Event (See
              <xref linkend="LoPAR.Virtualization" />).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
              <emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
              deliver &#8220;Partner partition suspended&#8221; CRQ Transport Events to
              both CRQs of all CRQ connections associated with the partition calling
              <emphasis>ibm,suspend-me.</emphasis></para>
              <para><emphasis role="bold">Note:</emphasis> The transport events are visible to the partition calling
              <emphasis>ibm,suspend-me</emphasis> after the subsequent resume from
              suspension, while the transport events are immediately visible to the
              partner partitions of the caller at the time of the suspend.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
              <emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
              set the state of all of the caller&#8217;s CRQs to disabled.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must implement the H_ENABLE_CRQ hcall() using the syntax and semantics
              described in
              <xref linkend="LoPAR.Virtualization" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For platforms that implement the Partition Suspension and VSCSI
              options:</emphasis> The
              <emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property of the
              platform&#8217;s
              <emphasis>v-scsi</emphasis> and
              <emphasis>v-scsi-host</emphasis> nodes must include
              <emphasis role="bold"><literal>&#8220;IBM,v-scsi-2&#8221;</literal></emphasis> and
              <emphasis role="bold"><literal>&#8220;IBM,v-scsi-host-2&#8221;</literal></emphasis> respectively
              indicating the platform supports the &#8220;Partner partition
              suspended&#8221; CRQ Transport Event.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> If the OS is
              participating in OS surveillance, to avoid a surveillance time out, the
              OS must disable surveillance (see
              <xref linkend="dbdoclet.50569332_60143" />) prior to calling
              <emphasis>ibm,suspend-me</emphasis>.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must implement the LRDR option (See
              <xref linkend="LoPAR.Virtualization" />).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The logical
              configuration of a partition, including its view of the
              <emphasis>rtas-display-device</emphasis>, and rtas tone facility must not
              change while a partition is suspended.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must not change the support for a system parameter during
              suspension.</para>
              <para>
              <emphasis role="bold">NOTE:</emphasis> If RTAS returns a status of -3 (System
              parameter not supported) prior to suspension, it returns a Status of -3
              for accesses to that same system parameter after suspension. Similarly if
              RTAS does not return a Status of -3 prior to suspension for a given
              system parameter, it does not do so after suspension.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must limit the system parameters that change values during suspension to
              those specified in
              <xref linkend="dbdoclet.50569332_10519" /> (all system parameters not
              specified are preserved).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must preserve up to the first 32 SLB entries for each partition processor
              during the suspension. Other SLB entries are subject to loss.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
          xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option with the Platform
              Facilities Option:</emphasis> The
              <emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
              calling partition has no outstanding coprocessor operations else return a
              status of -9005 &#8220;Outstanding COP Operations&#8221;.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_10519">
                <title>System Parameters that May Change During Partition
                Migration and Hibernation</title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="33*" />
                  <colspec colname="c2" colwidth="33*" />
                  <colspec colname="c3" colwidth="33*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">System Parameter Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">&#160;</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>0-15</para>
                      </entry>
                      <entry>
                        <para>HMC</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>18-19</para>
                      </entry>
                      <entry>
                        <para>Legacy processor CoD</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>20</para>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>SPLPAR characteristics</para>
                      </entry>
                      <entry>
                        <para>Only specified SPLPAR keywords may change value</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="6" valign="middle">
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>DesiredEntitledCapacity</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>DesiredMemory</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>DesiredNumberOfProcessors</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>DesiredVariableCapacityWeight</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>DispatchWheelRotationPeriod</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>MinimumEntitledCapacityPerVP</para>
                      </entry>
                      <entry>
                        <para>Platform prevents migration where current Entitled
                        Capacity/VCPU ratio would be below the target's minimum.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>MaximumPlatformProcessors</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>22</para>
                      </entry>
                      <entry>
                        <para>platform_auto_power_restart</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>23</para>
                      </entry>
                      <entry>
                        <para>sp-remote-pon</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>24</para>
                      </entry>
                      <entry>
                        <para>sp-rb4-pon</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>25</para>
                      </entry>
                      <entry>
                        <para>sp-snoop-str</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>30</para>
                      </entry>
                      <entry>
                        <para>sp-call-home</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>31</para>
                      </entry>
                      <entry>
                        <para>sp-current-flash-image</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>33</para>
                      </entry>
                      <entry>
                        <para>epow3-quiesce-time</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>34</para>
                      </entry>
                      <entry>
                        <para>memory-preservation-boot-time</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>35</para>
                      </entry>
                      <entry>
                        <para>SCSI initiator identifier</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>36</para>
                      </entry>
                      <entry>
                        <para>AIX support</para>
                      </entry>
                      <entry>
                        <para>The keyword &#8220;support&#8221; may not change to the
                        value &#8220;no&#8221; for an AIX client.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>37</para>
                      </entry>
                      <entry>
                        <para>enhanced processor CoD</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>38</para>
                      </entry>
                      <entry>
                        <para>enhanced memory CoD</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>39</para>
                      </entry>
                      <entry>
                        <para>CoD Options</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>41</para>
                      </entry>
                      <entry>
                        <para>firmware boot options</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>43</para>
                      </entry>
                      <entry>
                        <para>processor module information</para>
                      </entry>
                      <entry>
                        <para>&#160;</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_84414">
      <title><emphasis>ibm,update-nodes</emphasis> RTAS Call</title>

      <para>This RTAS call is used to determine which device tree nodes have
      changed due to a massive platform reconfiguration such as when the
      partition is migrated between machines. Differing platform
      reconfigurations are expected to potentially result in different sets of
      nodes being updated; the &#8220;scope&#8221; argument communicates what
      set of changes are to be reported. The work area is a 4 KB naturally
      aligned area of storage below the first 4 GB; as such, it may not be
      large enough to contain the reports of all changed nodes. The status
      value of 1 is used to inform the caller that there are more updates to
      report and that it will have to call the
      <emphasis>ibm,update-nodes</emphasis> RTAS again to receive them. On
      subsequent calls the state variable, which is set to zero on the first
      call, is set to the value returned on the previous call, to supply RTAS
      with the information it needs to continue from where the previous call
      ended.</para>
      <para>Upon return, the work area contains, in addition to the state
      variable, zero or more operation lists, and logically ends with a
      terminator (4 byte word naturally aligned containing 0x00000000). An
      operation list consists of an operator (4 bytes naturally aligned) and
      zero or more (up to a the maximum number of 4 byte locations remaining in
      the work area) operands, each 4 bytes long. An operator consists of a
      single byte opcode followed by 3 bytes encoded with the binary value of
      the number of operands that follow. An operator with an operand length
      field of zero performs no operation, and the opcode of zero is reserved
      for the terminator -- thus the terminator can be considered a special
      encoding of a no-op operator.</para>

      <itemizedlist>
        <listitem>
          <para>The opcode of 0x01 is used for deleted nodes -- the operands are
          the
          <emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
        </listitem>

        <listitem>
          <para>The opcode of 0x02 is used for updated nodes -- the operands are
          the
          <emphasis role="bold">phandle</emphasis> values for the updated nodes. The updated
          properties are obtained using the
          <emphasis>ibm,update-properties</emphasis> RTAS call.</para>
        </listitem>

        <listitem>
          <para>The opcode of 0x03 is used for adding nodes -- the operands are
          pairs of
          <emphasis role="bold">phandle</emphasis> and
          <emphasis role="bold">drc-index</emphasis> values; the
          <emphasis role="bold">phandle</emphasis> value denotes the parent node of the node to
          be added and the
          <emphasis role="bold">ibm,drc-index</emphasis> value is passed with the
          <emphasis>ibm,configure-connector</emphasis> RTAS call to obtain the
          contents of the added node.</para>
        </listitem>
      </itemizedlist>

      <para>To make processing of device tree updates simpler, all opcode 0x01
      (delete) operations (if any) are presented prior to all opcode 0x02
      (update) operations (if any), and finally any 0x03 (addition) operations
      are presented. The
      <emphasis role="bold">phandle</emphasis> operand values are the same
      <emphasis role="bold">phandle</emphasis> values as reported by the
      <emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
              include the
              <emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property in all OF nodes
              specified in
              <xref linkend="dbdoclet.50569332_80965" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
              implement the
              <emphasis>ibm,update-nodes</emphasis> RTAS call using the argument call
              buffer defined by
              <xref linkend="dbdoclet.50569332_55185" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55185">
                <title>Argument Call Buffer
                <emphasis>ibm,update-nodes</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="4" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,update-nodes</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>32 bit real address of work area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Scope</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Values per
                        <xref linkend="dbdoclet.50569332_80965" />.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy</para>
                        <para>-3: Parameter Error (Purpose does not match the current
                        partition state)</para>
                        <para>0: Success</para>
                        <para>1: More nodes updated -- call again</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,update-nodes</emphasis> RTAS call work area must be 4 KB
              long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else
              RTAS may return -3 &#8220;Parameter Error&#8221;.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,update-nodes</emphasis> RTAS for a given value of &#8220;
              <emphasis>Scope</emphasis>&#8221; must be formatted as specified in
              <xref linkend="dbdoclet.50569332_76526" />, else RTAS may return -3
              &#8220;Parameter Error&#8221;.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76526">
                <title>Initial Format of Work Area for
                <emphasis>ibm,update-nodes</emphasis></title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" align="center" />
                  <thead>
                    <row>
                      <entry>
                        <para>0x00000000 (State Variable indicates Initial call for
                        specified
                        <emphasis>Scope</emphasis>)</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>12 bytes of 0x00 (reserved)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Don&#8217;t Care . . .</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>Upon successful return (non-negative status
              value) from
              <emphasis>ibm,update-nodes</emphasis> the work area must by formatted as
              defined in
              <xref linkend="dbdoclet.50569332_64519" />. (Note each entry in
              <xref linkend="dbdoclet.50569332_64519" /> is 4 bytes long.)</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64519">
                <title>Format of Work Area for
                <emphasis>ibm,update-nodes</emphasis></title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" align="center" />
                  <tbody>
                    <row>
                      <entry>
                        <para>State Variable (4 Bytes)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>12 bytes of 0x00 (reserved)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0 or more operation lists</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>. . .</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Terminator (0x00000000)</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,update-nodes</emphasis> RTAS call operation list for the
              <emphasis>ibm,update-nodes</emphasis> RTAS call must contain an operator
              (4 bytes naturally aligned) and zero or more 4 byte operands up to the
              end of the work area.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para>An operator in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
              formatted with, starting at the high order byte, a single byte opcode
              followed by 3 bytes encoded with the binary value of the number of
              operands that follow.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para>An operator in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list with an
              operand length field of zero must be considered to perform no
              operation.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para>The opcode of 0x01 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
              used to denote node deletions.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para>The operands for opcode 0x01 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the

              <emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para>The opcode of 0x02 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
              used to denote updated nodes.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para>The operands for opcode 0x02 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the
              <emphasis role="bold">phandle</emphasis> values for the updated nodes that may be used
              as the
              <emphasis>ibm,update-properties</emphasis> RTAS call argument to obtain
              the changed properties of the updated node.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para>The opcode of 0x03 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must used
              for the added nodes.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
            <listitem>
              <para>The operands for opcode of 0x03 in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
              <emphasis role="bold">phandle</emphasis> and
              <emphasis role="bold">drc-index</emphasis> value pairs (each value being 4 bytes
              on a natural boundary totalling 8 bytes for the pair) denoting the parent
              node of the added node and the
              <emphasis>ibm,configure-connector</emphasis> RTAS call argument to obtain
              the contents of the added node respectively.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
            <listitem>
              <para>All opcode 0x01 (delete) in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
              must be presented prior to any opcode 0x02 (update) operations (if
              any).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
            <listitem>
              <para>All opcode 0x02 (update) in an
              <emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
              must be presented prior to any opcode 0x03 (add) operations (if
              any).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
            <listitem>
              <para>The work area on subsequent call(s) to
              <emphasis>ibm,update-nodes</emphasis> RTAS for the same value of the
              <emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> must be formatted as specified in
              <xref linkend="dbdoclet.50569332_64422" />, else RTAS may return -3
              &#8220;Parameter Error&#8221;.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64422">
                <title>Format of Work Area for Subsequent Calls to
                <emphasis>ibm,update-nodes</emphasis></title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" align="center" />
                  <thead>
                    <row>
                      <entry>
                        <para>Value of the 1st 16 bytes of the returned work area from
                        last call to
                        <emphasis>ibm,update-nodes</emphasis> RTAS that returned status
                        of 1.</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>Don&#8217;t Care . . .</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
            <listitem>
              <para>The &#8220;<emphasis>Scope</emphasis>&#8221; argument for the
              <emphasis>ibm,update-nodes</emphasis> RTAS call must be one of the values
              specified in the scope value column of
              <xref linkend="dbdoclet.50569332_80965" />, else RTAS may return -3
              &#8220;Parameter Error&#8221;.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
            <listitem>
              <para>For the
              <emphasis>ibm,update-nodes</emphasis> RTAS call, the platform must
              restrict its reported node updates to those specified in
              <xref linkend="dbdoclet.50569332_80965" /> for the value of the specified
              <emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para>

            </listitem>
       	</varlistentry>

        <varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
          xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
            <listitem>
              <para>The work area on the first call to
              <emphasis>ibm,update-nodes</emphasis> RTAS for a given value of
              <emphasis>"Scope"</emphasis> must be formatted as specified in
              <xref linkend="table_initial_format_of_work_area_for_ibm_update_nodes"/>
              else RTAS may return -3 "Parameter Error".</para>

              <table frame="all" pgwide="1" xml:id="table_initial_format_of_work_area_for_ibm_update_nodes">
                <title>Initial Format of Work Area for
                <emphasis>ibm,update-nodes</emphasis> with Device Reconfiguration Scope</title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" align="center"/>
                  <tbody>
                    <row>
                      <entry>
                        <para>0x00000000 (State Variable indicates Initial call for specified <emphasis>Scope</emphasis>)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Unit Address of target device for reconfiguration</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>4 bytes of 0x00 (reserved)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Don't Care. . .</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_80965">
        <title>Nodes That May be Reported by
        <emphasis>ibm,update-nodes</emphasis> for a Given Value of the
        &#8220;<emphasis>Scope</emphasis>&#8221; Argument</title>
        <tgroup cols="3">
          <colspec colname="c1" colwidth="33*" />
          <colspec colname="c2" colwidth="33*" />
          <colspec colname="c3" colwidth="33*" />
          <thead>
            <row>
              <entry>
                <para>Scope Value</para>
              </entry>
              <entry>
                <para>Reportable node types (value of
                <emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> or
                <emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> property)</para>
              </entry>
              <entry>
                <para>Supported Opcodes</para>
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry morerows="7" valign="middle">
                <para>Negative values: Platform Resource Reassignment events as
                from
                <emphasis>event-scan</emphasis> RTAS</para>
              </entry>
              <entry>
                <para><emphasis role="bold">cpu</emphasis></para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><emphasis role="bold">memory</emphasis></para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><emphasis role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,plaform-facilities</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,random-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,compression-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,encryption-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry morerows="13" valign="middle">
                <para>1 Partition Migration / Hibernation</para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">root</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">openprom</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">rtas</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">vdevice</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">cpu</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">cache</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">options</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">memory</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><emphasis  role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
              </entry>
              <entry>
                <para>&lt;all&gt;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><emphasis  role="bold">ibm,platform-facilities</emphasis></para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,random-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,compression-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,encryption-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x01-0x03</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>2 Activate Firmware</para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">rtas</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry morerows="1" valign="middle">
                <para>3 Device Reconfiguration</para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">ibm,coherent-platform-facility</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">ibm,coherent-platform-function</emphasis>
                </para>
              </entry>
              <entry>
                <para>0x02</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

    </section>

    <section xml:id="dbdoclet.50569332_40069">
      <title><emphasis>ibm,update-properties</emphasis> RTAS Call</title>

      <para>This RTAS call is used to report updates to the properties changed
      due to a massive platform reconfiguration such as when the partition is
      migrated between machines. This RTAS call reports changes in the node
      specified by the phandle value in the work area passed using the Work
      Area Address argument. The phandle value may be that of a critical node
      that the caller is interested in or one reported by
      <emphasis>ibm,update-nodes</emphasis> RTAS call. These changes may include
      any combination of new values, deleted and added properties. Updates for
      a given node are retained until the platform is subsequently
      reconfigured, and remain available to subsequent calls to
      <emphasis>ibm,update-nodes</emphasis>.</para>
      <para>There may be more changes than can be reported in a single 4 K work
      area. In this case, the RTAS call returns with a status of 1 &#8220;More
      properties updated -- call again&#8221;. On the first call, the second
      word of the work area contains the value 0 specifying that the RTAS call
      is to start with the first changed property for the specified updated
      node. On a call with a status value of 1, the first sixteen (16) bytes of
      the work area contain values that, when subsequently supplied in the work
      area of another call to
      <emphasis>ibm,update-properties</emphasis> RTAS, specify that the call
      returns the updated property data for properties after those reported in
      the previous call.</para>
      <para>A single updated property value string may exceed the capacity of a
      single 4 K work area. In that case, the updated property value descriptor
      for the property appears in the work area of multiple sequential calls to
      <emphasis>ibm,update-properties</emphasis> RTAS. When the updated property
      value descriptor contains the final data for the property value, the
      property string length field of the updated property value descriptor is
      a positive number. When the updated property value descriptor contains
      either the initial or interim data for the property value, the updated
      property string length field is a negative number denoting the twos
      complement of the length of the updated property string contained in the
      work area. The data value strings for a given property name are
      concatenated until the final updated property value descriptor is
      processed.</para>
      <para>The first value returned, with an updated property name string of
      NULL, is always the node&#8217;s name (for example: full path ||
      <emphasis>name</emphasis> property value || @ unit address) even if there
      has been no change.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
              implement the
              <emphasis>ibm,update-properties</emphasis> RTAS call using the argument
              call buffer defined by
              <xref linkend="dbdoclet.50569332_63317" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_63317">
                <title>Argument Call Buffer
                <emphasis>ibm,update-properties</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Parameter Type</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Values</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="4" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,update-properties</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work Area Address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>32 bit real address of work area</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Scope</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Values per
                        <xref linkend="dbdoclet.50569332_71049" />.</para>
                      </entry>
                    </row>
                    <row>
                      <entry valign="middle">
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy</para>
                        <para>-3: Parameter Error (Purpose does not match the current
                        partition state)</para>
                        <para>0: Success</para>
                        <para>1: More properties updated -- call again</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,update-properties</emphasis> RTAS call must be 4 KB long
              aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS
              may return -3 &#8220;Parameter Error&#8221;.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>The work area on the first call to
              <emphasis>ibm,update-properties</emphasis> RTAS for a given updated node
              must be formatted as specified in
              <xref linkend="dbdoclet.50569332_84989" />, else RTAS may return -3
              &#8220;Parameter Error&#8221;.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_84989">
                <title>Initial Format of Work Area for
                <emphasis>ibm,update-properties</emphasis></title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                        <emphasis role="bold">phandle</emphasis> of updated node containing updated
                        properties to be reported (4 bytes)</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>0x00000000 (Indicates Initial call for specified
                        <emphasis role="bold">phandle</emphasis>)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>8 bytes of 0x00 (reserved)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Don&#8217;t Care . . .</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para>Upon successful return (non-negative status
              value) from
              <emphasis>ibm,update-properties</emphasis> the work area must by formatted
              as defined in
              <xref linkend="dbdoclet.50569332_72959" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_72959">
                <title>Return Format of Work Area for
                <emphasis>ibm,update-properties</emphasis></title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Description</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Comments</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>
                        <emphasis role="bold">phandle</emphasis> of updated node containing updated
                        properties to be reported.</para>
                      </entry>
                      <entry>
                        <para>4 Bytes</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>State Variable</para>
                        <para>(to be returned if status argument value = 1)</para>
                      </entry>
                      <entry>
                        <para>4 Bytes</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>8 bytes</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Number of properties reported in the work area</para>
                      </entry>
                      <entry>
                        <para>4 Bytes</para>
                        <para>The number (N) of updated property value descriptors that
                        follow -- see below</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>N updated property value descriptors</para>
                      </entry>
                      <entry>
                        <para>Each updated property value descriptor is formatted
                        as:</para>
                        <para>&#160;</para>
                        <para>Null terminated string indicating the name of the updated
                        property.</para>
                        <para>followed by:</para>
                        <para>Value Descriptor -- 4 Bytes decoded as</para>
                        <para>&#160;</para>
                        <para>0x00000000 Name only property (
                        <emphasis role="bold"><literal>&#8220;encode-null&#8221;</literal></emphasis>) no value
                        follows</para>
                        <para>&#160;</para>
                        <para>0x80000000 The property is to be deleted no value
                        follows</para>
                        <para>&#160;</para>
                        <para>Other positive values are the length (M) of the
                        immediately following property value string that completes the
                        update of the property value.</para>
                        <para>&#160;</para>
                        <para>Other negative values are the twos complement of the
                        length (M) of the immediately following property value string
                        that either starts or continues the update of the property
                        value with the remainder in the work area of subsequent call(s)
                        to
                        <emphasis>ibm,update-properties</emphasis>.</para>
                        <para>&#160;</para>
                        <para>Followed by:</para>
                        <para>0-M bytes of property value string.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>Upon successful return (non-negative status
              value) from
              <emphasis>ibm,update-properties</emphasis> when the State Variable had
              been 0x00000000, the first updated property descriptor must describe the
              fully qualified path name of the node specified by the phandle argument
              in the work buffer; the three fields of this updated property descriptor
              are:</para>

              <itemizedlist>
                <listitem>
                  <para>Property name string is as from
                  <emphasis>encode-null</emphasis></para>
                </listitem>

                <listitem>
                  <para>Value descriptor is the 4 byte binary length of the value
                  string</para>
                </listitem>

                <listitem>
                  <para>Value string is the fully qualified path name as from the node
                  name string returned by the open firmware
                  <emphasis>package-to-path</emphasis> client interface call.</para>
                </listitem>
              </itemizedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para>The work area on subsequent call(s) to
              <emphasis>ibm,update-properties</emphasis> RTAS for a given updated node
              must be formatted as specified in
              <xref linkend="dbdoclet.50569332_96468" />, else RTAS may return -3
              &#8220;Parameter Error&#8221;.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_96468">
                <title>Format of Work Area for Subsequent Calls to
                <emphasis>ibm,update-properties</emphasis></title>
                <tgroup cols="1">
                  <colspec colname="c1" colwidth="100*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                        <emphasis role="bold">phandle</emphasis> of updated node containing updated
                        properties to be reported (4 Bytes)</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>Value from last call to
                        <emphasis>ibm,update-properties</emphasis> RTAS that returned
                        status of 1 (12 bytes).</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Don&#8217;t Care . . .</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,update-properties</emphasis> RTAS call, the platform must
              restrict its reported property updates to those specified in
              <xref linkend="dbdoclet.50569332_71049" /> for the value of the specified
              <emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para>For the
              <emphasis>ibm,update-properties</emphasis> RTAS call, the platform must
              return a
              <emphasis>Status</emphasis> of -3 (Parameter Error) for an unrecognized
              value of the &#8220;Scope&#8221; argument.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71049">
                <title>Properties of the Nodes That May Be Reported by
                <emphasis>ibm,update-properties</emphasis> for a &#8220;
                <emphasis>Scope</emphasis>&#8221;</title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="33*" />
                  <colspec colname="c2" colwidth="33*" />
                  <colspec colname="c3" colwidth="33*" />
                  <thead>
                    <row>
                      <entry>
                        <para>Scope Value</para>
                      </entry>
                      <entry>
                        <para>Reportable node types (value of
                        <emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> or
                        <emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> property)</para>
                      </entry>
                      <entry>
                        <para>Property Name</para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="6" valign="middle">
                        <para>All negative values: Resource Reassignment events as from
                        event-scan RTAS</para>
                      </entry>
                      <entry>
                        <para>/memory</para>
                      </entry>
                      <entry>
                        <para><emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>ibm,dynamic-reconfiguration-memory</para>
                      </entry>
                      <entry>
                        <para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis></para>
                        <para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>cpu</para>
                      </entry>
                      <entry>
                        <para>&#8220;ibm,associativity&#8221;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="31" valign="middle">
                        <para>1 Partition Migration / Hibernation</para>
                      </entry>
                      <entry morerows="18" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>root</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,model-class&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,extended-clock-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;system-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,aix-diagnostics&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,diagnostic-lic&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,ignore-hp-po-fails-for-dlpar&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,managed-address-types&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,service-indicator-mode&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>openprom</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="9" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>rtas</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;power-on-max-latency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,associativity-reference-points&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,max-associativity-domains&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,configure-kernel-dump-version&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,read-slot-reset-state-functions&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,configure-pe&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,change-msix-capable&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,current-associativity-domains&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>vdevice</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>children of the
                        <emphasis role="bold"><literal>vdevice</literal></emphasis> node</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="31" valign="middle">
                        <para>1 Partition Migration / Hibernation</para>
                        <para>&#160;</para>
                      </entry>
                      <entry morerows="20" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>cpu</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;d-cache-sets&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;d-cache-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;i-cache-sets&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;i-cache-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;bus-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,extended-bus-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>
                          &#8220;ibm,extended-clock-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;timebase-frequency&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;l2-cache&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;performance-monitor&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>TLB properties (See
                        <xref linkend="LoPAR.DeviceTree" />)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;slb-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,tbu40-offset&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,pi-features&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,spurr&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,pa-optimizations&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                        <emphasis role="bold"><literal>&#8220;ibm,dfp&#8221;</literal></emphasis> (sign bit
                        only)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,sub-processors&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="4" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>cache</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;d-cache-sets&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;d-cache-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;i-cache-sets&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;i-cache-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>l2-cache</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>options</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,dasd-spin-interval&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>memory</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="2" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>ibm,dynamic-reconfiguration-memory</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para><emphasis role="bold"><literal>&#8220;ibm,associativity-lookup-arrays&#8221;</literal></emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis></para>
                        <para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis></para>
                        <para>only the associativity list index fields</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para><emphasis role="bold"><literal>&#8220;ibm,memory-preservation-time&#8221;</literal></emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>/chosen</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis>
                        </para>
                        <para>byte 3 (I/O Super Page Option support parameters)</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="3" valign="middle">
                        <para>1 Partition Migration / Hibernation</para>
                        <para>&#160;</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>&lt;all&gt;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>2 Activate Firmware</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>rtas</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <orderedlist>
                          <listitem>
                            <para>Any
                            <emphasis role="bold"><literal>/rtas</literal></emphasis> node property as defined per LoPAR
                            remains invariant.</para>
                          </listitem>

                          <listitem>
                            <para>Any
                            <emphasis role="bold"><literal>/rtas</literal></emphasis> node property or definition
                            extension, except for the value of a function token property*,
                            may change (provided that the client program has indicated
                            support for such property or definition extension) including
                            the following:</para>
                            <para>
                              <emphasis role="bold"><literal>&#8220;ibm,read-slot-reset-state-functions&#8221;
                              &#8220;ibm,configure-pe&#8221;</literal></emphasis>
                            </para>
                          </listitem>
                        </orderedlist>
                        <para>*NOTE: This exception mandates that if an RTAS function
                        token property survives a firmware activation, the token value
                        of that RTAS function call does not change.</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="34" valign="middle">
                        <para>3 Device Reconfiguration</para>
                      </entry>
                      <entry morerows="10" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>ibm,coherent-platform-facility</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,caia-version&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,psl-revision&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="23" valign="middle">
                        <para>
                          <emphasis role="bold"><literal>ibm,coherent-platform-function</literal></emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,max-ints-per-process&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,min-ints-per-process&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,#processes&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,config-record-type&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,config-record-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,#config-records&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,error-buffer-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,scratchpad-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,supports-aur&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,supports-csrp&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,supports-prr&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,process-mmio-size&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold"><literal>&#8220;ibm,programming-models&#8221;</literal></emphasis>
                        </para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
      </variablelist>


    </section>

    <section xml:id="dbdoclet.50569332_67111">
      <title><emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call</title>

      <para>This RTAS call is used to register and unregister with the platform
      a data structure describing kernel dump information. This dump
      information is preserved as needed by the platform in support of a
      platform assisted kernel dump option.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              option:</emphasis> The platform must implement the
              <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call using the
              argument call buffer defined by
              <xref linkend="dbdoclet.50569332_24141" />.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24141">
                <title>Argument Call Buffer
                <emphasis>ibm,configure-kernel-dump</emphasis></title>
                <tgroup cols="3">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="2*" />
                  <colspec colname="c3" colwidth="4*" />
                  <tbody>
                    <row>
                      <entry>
                        <para>Parameter Type</para>
                      </entry>
                      <entry>
                        <para>Name</para>
                      </entry>
                      <entry>
                        <para>Values</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="5" valign="middle">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for
                        <emphasis>ibm,configure-kernel-dump</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>3</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Command</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1: Register for future kernel dump</para>
                        <para>2: Unregister for future kernel dump</para>
                        <para>3: Complete/Invalidate current kernel dump</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work_buffer_address</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>When command is 1: Register for future kernel dump,
                        points to a structure as defined in
                        <xref linkend="dbdoclet.50569332_76933" />.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Work_buffer_length</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Length of Kernel Dump Memory Structure when defined
                        above</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>0: Success</para>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy</para>
                        <para>-3: Parameter Error</para>
                        <para>-9: Dump Already Registered</para>
                        <para>-10: Dump Active</para>
                        <para>990x:Extended Delay</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              option:</emphasis> The work-buffer address and work-buffer-length for the
              <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call must point to an
              RMR-memory buffer that contains the structures described in
              <xref linkend="dbdoclet.50569332_76933" />, whenever the command is 1,
              register for future kernel dump; otherwise the call may return -3,
              &#8220;Parameter Error.&#8221;</para>
              <para>The Dump Memory Structure specified in
              <xref linkend="dbdoclet.50569332_76933" /> is passed by the operating
              system during a
              <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call. It is also
              reported by the platform using the
              <emphasis>ibm,kernel-dump</emphasis> RTAS property after a dump has been
              initiated.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76933">
                <title>Kernel Assisted Dump Memory Structure</title>
                <tgroup cols="5">
                  <colspec colname="c1" colwidth="1*" />
                  <colspec colname="c2" colwidth="1*" />
                  <colspec colname="c3" colwidth="1*" />
                  <colspec colname="c4" colwidth="2*" />
                  <colspec colname="c5" colwidth="2*" />
                  <thead>
                    <row>
                      <entry nameend="c5" namest="c1">
                        <para>
                          <emphasis>Header</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>Offset</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>Number of Bytes</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Value</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x0</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Dump Format Version = 0x00000001</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x4</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>2</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Number of Kernel Dump Sections</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x6</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>2</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Dump Status Flags</para>
                        <para>A bit mask with value</para>
                        <para>0x8000 = Dump performed (Set to 0 by caller of the
                        ibm,configure-kernel-dump call)</para>
                        <para>0x4000 = Dump was triggered by the previous system boot
                        (set by platform)</para>
                        <para>0x2000 = Dump error occurred (set by platform)</para>
                        <para>All other bits reserved</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x8</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Offset to first Kernel Dump Section, offset from the
                        beginning of the Structure</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0xc</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Number of bytes in a block of the dump-disk, if data to
                        be written to a dump-disk, If not, should be set to 0
                        (indicating the no disk dump option.)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x10</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Starting block# offset on dump-disk (set to 0 for the no
                        disk dump option)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x18</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Number of blocks on dump-disk usable for dump (set to 0
                        for the no disk dump option)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x20</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Offset from start of structure to a Null-terminated
                        Dump-disk path string (set to 0 for the no disk dump
                        option)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>0x24</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Maximum time allowed (milliseconds) after
                        Non-Maskable-Interrupt for the OS to call
                        <emphasis>ibm,configure-kernel-dump</emphasis>
                        <emphasis>Function</emphasis> 2 (unregister) to prevent an
                        automatic dump-reboot (set to 0 to disable the automatic
                        dump-reboot function)</para>
                      </entry>
                    </row>
                    <row>
                      <entry nameend="c5" namest="c1">
                        <para>
                          <emphasis>Dump-disk Path String</emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Offset specified above</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>Varies</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Null-terminated Dump-disk path string specifying the
                        dump-disk. If no disk dump option is indicated, this section is
                        not included.</para>
                      </entry>
                    </row>
                    <row>
                      <entry nameend="c5" namest="c1">
                        <para>
                          <emphasis>First Kernel Dump Section</emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Offset specified above</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>4</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Dump Request Flags:</para>
                        <para>A bit-mask</para>
                        <para>Bit 0x00000001 When set, firmware to copy source data to
                        partition memory. This option must be selected if no disk dump
                        option is indicated.</para>
                        <para>All other bit values reserved</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+4</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>2</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Source Data type, describes section of dump memory being
                        described</para>
                        <para>0x0001 = CPU State Data</para>
                        <para>0x0002 = Hardware Page Table for Real Mode Region</para>
                        <para>0x0011 = Real Mode Region</para>
                        <para>0x0012 = Dump OS identified string (identifies that the
                        dump is for a particular OS type and version)</para>
                        <para>0x0100 - 0xFFFF OS defined source types</para>
                        <para>All Other values reserved</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+6</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>2</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Dump Error Flags (set by platform)</para>
                        <para>Bit mask</para>
                        <para>0x8000 = Invalid section data type</para>
                        <para>0x4000 = Invalid source address</para>
                        <para>0x2000 = Requested section length exceeds source</para>
                        <para>0x1000 = Invalid partition destination address</para>
                        <para>0x0800 = Partition memory destination too small</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+8</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Source address (logical address if section came from
                        partition memory, or byte offset if section is platform
                        memory)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+16</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Requested data length, represents number of bytes to
                        dump</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+24</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Actual data length, number of bytes dumped</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Section Start+32</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>8</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>Destination address, logical address used for sections
                        not written to disk by the platform, always required for a Real
                        mode region section and for all sections when the no disk dump
                        option is used.</para>
                      </entry>
                    </row>
                    <row>
                      <entry nameend="c5" namest="c1">
                        <para>
                          <emphasis>Subsequent Sections</emphasis>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Previous Section Start+40</para>
                      </entry>
                      <entry nameend="c3" namest="c2">
                        <para>Start of Next Section</para>
                      </entry>
                      <entry nameend="c5" namest="c4">
                        <para>A total of up to nine additional 40 bytes sections with
                        values as described in the First Section may be specified so
                        long as the entire structure does not exceed 512 bytes for
                        version 1.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis>ibm,os-term</emphasis> RTAS call, or on a system reset without
              an
              <emphasis>ibm,nmi-interlock</emphasis> RTAS call, if the platform has a
              dump structure registered through the
              <emphasis>ibm,configure-kernel-dump</emphasis> call, the platform must
              process each registered kernel dump section as required and, when
              available, present the dump structure information to the operating system
              through the
              <emphasis role="bold"><literal>&#8220;ibm,kernel-dump&#8221;</literal></emphasis> property, updated with
              status for each dump section, until the dump has been invalidated through
              the
              <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
              register or unregister for a dump while a dump is currently active, the
              platform must return a
              <emphasis>Status</emphasis> of -9, &#8220;Dump Active&#8221; indicating
              that a dump has been copied by the platform and a call must be made to
              complete/invalidate the active dump before another call to register or
              unregister a dump can be completed successfully.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
              register a dump after a dump has already been registered by a call, the
              platform must return a
              <emphasis>Status</emphasis> of -8, &#8220;Dump Already Registered&#8221;
              unless an intervening call was made to invalidate the previously
              registered dump.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              Option:</emphasis> Partition memory not specifically mentioned in the call
              structure must be preserved by the platform at the same location as
              existed prior to the os termination or platform reboot.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              Option:</emphasis> The platform must present the RTAS property,
              <emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis> in the
              OF device tree, which describes how much space is required to store dump
              data for the firmware provided dump sections, where the firmware defined
              dump sections are:</para>

              <itemizedlist>
                <listitem>
                  <para>0x0001 = CPU State Data</para>
                </listitem>

                <listitem>
                  <para>0x0002 = Hardware Page Table for Real Mode Region</para>
                </listitem>
              </itemizedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              Option:</emphasis> The platform must present the RTAS property,
              <emphasis role="bold"><literal>&#8220;ibm-configure-kernel-dump-version&#8221;</literal></emphasis> in
              the OF device tree.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
              Option:</emphasis> After a dump registration is disabled (for example, by
              a partition migration operation), calls to
              <emphasis>ibm,os-term</emphasis> must return to the OS as though a dump
              was not registered.</para>
              <para>
              <emphasis role="bold">Programming Note:</emphasis> The intended flow of interactions
              that utilize this call is as follows:</para>

              <orderedlist>
                <listitem>
                  <para>The OS registers sections of memory for dump preservation during
                  OS initialization</para>
                </listitem>

                <listitem>
                  <para>The OS terminates abnormally</para>
                </listitem>

                <listitem>
                  <para>The Platform moves registered sections of memory as instructed
                  during dump registration.</para>
                </listitem>

                <listitem>
                  <para>The Partition reboots and provides the prior registration data
                  in the device tree.</para>
                </listitem>

                <listitem>
                  <para>The OS writes the preserved memory regions to disk before using
                  those memory regions for regular use</para>
                </listitem>

                <listitem>
                  <para>The OS completes/invalidates current dump status.</para>
                </listitem>

                <listitem>
                  <para>The OS must use H_CLEAR_HPT to clear the page table if running
                    in XIVE Exploitation Mode, H_REMOVE is not a sufficient mechanism
                    to clear the HPT. Failure to use H_CLEAR_HPT may result in H_READ
                    returning invalid entries as valid.</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="dbdoclet.50569332_14137">
      <title>DMA Window Manipulation Calls</title>

      <para>DMA windows for a PE can be changed by the OS when the platform
      implements the Dynamic DMA Windows (DDW) option for a PE. The occurrence
      of the
      <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property in any node
      of the OF Device Tree indicates that the platform implements the DDW
      option, but that property is required to be in the bridge above a PE in
      order for the DDW RTAS call to be applicable for the PE. That is, DDW may
      be applicable to some PEs in a platform and not for others.</para>
      <para>The platform may implement the DDW RTAS calls even when the OS does
      not support these, because they are not required to be used by the OS,
      because there is always a default window initially allocated below 4 GB,
      as specified by the
      <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property. During
      partition migration, these RTAS calls may come and go, but so will the
      <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property as the
      nodes in which those are supported come or go.</para>
      <para>The following is an example of how an OS may grab all DMA window
      resources allocated for a PE:</para>

      <orderedlist>
        <listitem>
          <para>If the default window (as specified by the
          <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for the PE) is
          not needed, then call
          <emphasis>ibm,remove-pe-dma-window</emphasis> for the PE, specifying the
          default window LIOBN, to make the maximum resources available for the
          <emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>
        </listitem>

        <listitem xml:id="dbdoclet.50569332_89344">
          <para>Call
          <emphasis>ibm,query-pe-dma-window</emphasis> for the PE to get the
          <emphasis>Windows Available</emphasis> and
          <emphasis>PE TCEs</emphasis> available for the PE. If the
          <emphasis>Windows Available</emphasis> field indicates 1 or more and the
          <emphasis>PE TCEs</emphasis> field is non-zero, then continue.</para>
        </listitem>

        <listitem>
          <para>Call <emphasis>ibm,create-pe-dma-window</emphasis> for the PE, specifying the
          size based on the
          <emphasis>PE TCEs</emphasis> field obtained from the
          <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call in step
          <xref linkend="dbdoclet.50569332_89344" /> and on the I/O page size being
          specified.</para>
        </listitem>

        <listitem>
          <para>If the <emphasis>Windows Available</emphasis> field indicated 2 or more in step
          <xref linkend="dbdoclet.50569332_89344" />, then go back to step
          <xref linkend="dbdoclet.50569332_89344" /> and repeat, otherwise
          finished.</para>
        </listitem>
      </orderedlist>
      <para>
      <emphasis role="bold">Software Implementation Note:</emphasis> The general expectation
      is that if the
      <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property exists for
      a PE, that the OS will be able to generate one or more windows whose
      total size is larger than what is available via the default window. This
      requires either additional TCEs being available or that I/O page sizes
      other than 4 KB are available and the PE can use the largest I/O page
      size (the default window using only the 4 KB I/O page size). If not, then
      removing the default window would only allow re-allocation of the same
      size window at a different bus address (that is, same number of TCEs and
      same I/O page size). However, it may be possible for this to happen, in
      which case the platform may indicate that DDW is available to a PE, but
      removal of the default window will only allow creation of the same size
      window. An example is when a larger I/O page size is available but only
      the TCEs in the default window are available, and the PE cannot make use
      of the larger page size.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
              platform must implement all of the following RTAS calls:
              <emphasis>ibm,query-dma-window</emphasis>,
              <emphasis>ibm,create-dma-window</emphasis>, and
              <emphasis>ibm,remove-dma-window.</emphasis></para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
              platform must provide the
              <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property in the OF
              Device Tree in the bridge above each PE for which the DDW option is
              supported.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
              software must not call the
              <emphasis>ibm,query-dma-window</emphasis>,
              <emphasis>ibm,create-dma-window</emphasis>, or
              <emphasis>ibm,remove-dma-window</emphasis> RTAS calls in the absence of
              the
              <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property for the PE,
              otherwise the call returns a
              <emphasis>Status</emphasis> of -3 (Parameter error), and when the property
              does exist, software must use the token values specified in the
              <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property for these
              RTAS calls.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
              platform must provide a default DMA window for each PE, and all of the
              following must be true:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>The window is defined by the
                  <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
                  device tree.</para>
                </listitem>

                <listitem>
                  <para>The window is defined with 4 KB I/O pages.</para>
                </listitem>

                <listitem>
                  <para>The window is located entirely below 4 GB.</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569332_79382">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
              The platform must remove any DMA windows created by the
              <emphasis>ibm,create-pe-dma-window</emphasis> RTAS call for a PE and must
              restore the default DMA window (if it was removed) for the PE, as
              originally defined by the
              <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> properties for the PE,
              in each of the following cases:</para>

              <orderedlist numeration="loweralpha">
                <listitem>
                  <para>On a reboot of the partition</para>
                </listitem>

                <listitem>
                  <para>On a DR isolate operation that encompasses the PE</para>
                </listitem>
              </orderedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569332_72212">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
              In Requirement
              <xref linkend="dbdoclet.50569332_79382" />, the platform must provide the
              same LIOBN, location, and size as specified in the
              <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
              Device Tree for the device.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="dbdoclet.50569332_99826">
        <title><emphasis>ibm,query-pe-dma-window</emphasis></title>

        <para>This RTAS call allows for the discovery of the resources necessary
        to make a successful subsequent call to
        <emphasis>ibm,create-dma-window</emphasis>.</para>

        <para>If the <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call is made with Number Outputs
        equal to 6, and the <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis>
        property does not include list index of 3,
        then the call will return a Status of -3 (Invalid Parameter).</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a
                <emphasis>ibm,query-pe-dma-window</emphasis> call using the argument call
                buffer defined by
                <xref linkend="dbdoclet.50569332_53901" />.</para>

                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_53901">
                  <title>Argument Call Buffer
                  <emphasis>ibm,query-pe-dma-window</emphasis></title>
                  <tgroup cols="3">
                    <colspec colname="c1" colwidth="1*" />
                    <colspec colname="c2" colwidth="2*" />
                    <colspec colname="c3" colwidth="4*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Parameter Type</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Name</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Values</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="5" valign="middle">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for
                          <emphasis>ibm,query-pe-dma-window</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>3</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>5 or 6. The value 6 may be used when the ibm,ddw-extensions property
                          in the PHB node specified by this call indicates support for a 64-bit value of
                          PE TCEs. See <xref linkend="dbdoclet.50569332_25585" />.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>PE configuration address (Register fields set to
                          0)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PHB_Unit_ID_Hi</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Represents the most-significant 32-bits of the Unit ID of
                          the PHB that corresponds to the
                          <emphasis>config_addr</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PHB_Unit_ID_Low</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Represents the least-significant 32-bits of the Unit ID
                          of the PHB that corresponds to the
                          <emphasis>config_addr</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="5" valign="middle">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Parameter error</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Windows Available</para>
                        </entry>
                        <entry>
                          <para>Number of additional DMA windows that can be created for
                          this PE. If the value is 0 and the default window (as specified
                          by the
                          <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for
                          the PE) has not been yet removed via the
                          <emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call for that
                          window, and if the default window is not needed, then removal
                          of the default window makes at least one window
                          available.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>PE TCEs hi</para>
                        </entry>
                        <entry>
                          <para>Represents the most-significant 32-bits of the largest contiguous
                          block of TCEs allocated specifically for (that is, are reserved for) this PE.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>PE TCEs lo</para>
                        </entry>
                        <entry>
                          <para>Represents the least-significant 32-bits of the largest contiguous block
                          of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement
                          <xref linkend="dbdoclet.50569332_91197" />.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>IO Page Sizes</para>
                        </entry>
                        <entry>
                          <para>I/O Page Size Support. I/O page sizes supported for this
                          PE. This is a bit significant field, defined as follows:</para>
                          <para>Bits 0 - 23 reserved</para>
                          <para>24 = 16 GB page size supported</para>
                          <para>25 = 256 MB page size supported</para>
                          <para>26 = 128 MB pages supported</para>
                          <para>27 = 64 MB page size supported</para>
                          <para>28 = 32 MB page size supported</para>
                          <para>29 = 16 MB page size supported</para>
                          <para>30 = 64 KB page size supported</para>
                          <para>31 = 4 KB page size supported</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Migration Capable</para>
                        </entry>
                        <entry>
                          <para>H_MIGRATE_DMA Mask. Mask to indicate for which page sizes
                          (as specified in the I/O Page Size Support field), that
                          H_MIGRATE_DMA is supported (for this PE). This is a bit
                          significant field, with the bits defined to align to the bits
                          in the I/O Page Size Support field.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569332_91197">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
                TCE resources returned in the
                <emphasis>PE TCEs</emphasis> parameter of the
                <emphasis>ibm,query-dma-window</emphasis> RTAS call must be allocated to
                the PE specified by the PE configuration address specified in the call,
                and must be available to a subsequent
                <emphasis>ibm,create-dma-window</emphasis> RTAS call for that PE.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="dbdoclet.50569332_49009">
        <title><emphasis>ibm,create-pe-dma-window</emphasis></title>

        <para>This call allows the creation of a new DMA window, given the size
        of the DMA window, I/O page size, and the PE to which it is associated.
        The return from the call includes the LIOBN of the new DMA window, the
        starting I/O address of the DMA window, and size.</para>
        <para>
        <emphasis role="bold">Software Implementation Note:</emphasis> Software is expected to
        not attempt to create a DMA window that is larger than possible, or
        create more DMA windows than is possible, otherwise the
        <emphasis>ibm,create-pe-dma-window</emphasis> will return a
        <emphasis>Status</emphasis> of -3 (Parameter Error). Thus, the OS is
        expected to use the
        <emphasis>ibm,query-pe-dma-window</emphasis> first and not ask to create a
        window that consumes more resources than those that are available to the
        PE.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_49009"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
                implement the
                <emphasis>ibm,create-dma-window</emphasis> call using the argument call
                buffer defined by
                <xref linkend="dbdoclet.50569332_26269" />.</para>

                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26269">
                  <title>Argument Call Buffer
                  <emphasis>ibm,create-pe-dma-window</emphasis></title>
                  <tgroup cols="3">
                    <colspec colname="c1" colwidth="1*" />
                    <colspec colname="c2" colwidth="2*" />
                    <colspec colname="c3" colwidth="4*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Parameter Type</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Name</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Values</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="7" valign="middle">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for
                          <emphasis>ibm,create-pe-dma-window</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>5</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>4</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>PE configuration address (Register fields set to
                          0)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PHB_Unit_ID_Hi</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Represents the most-significant 32-bits of the Unit ID of
                          the PHB that corresponds to the
                          <emphasis>config_addr</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PHB_Unit_ID_Low</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Represents the least-significant 32-bits of the Unit ID
                          of the PHB that corresponds to the
                          <emphasis>config_addr</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>I/O Page Size</para>
                        </entry>
                        <entry>
                          <para>The value n, where 2
                          <emphasis>n</emphasis> is the requested I/O page size. Only page
                          sizes obtained from the
                          <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call for the
                          PE are allowed. Values of n from 0-11 are invalid.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Requested Window Size</para>
                        </entry>
                        <entry>
                          <para>The value n, where 2
                          <emphasis>n</emphasis> is the requested DMA window size.</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="3" valign="middle">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>990x: Extended delay, where x is a number 0-5 (see
                          text)</para>
                          <para>0: Success (window created)</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Busy, try again later</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>LIOBN</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>LIOBN of the DMA window created by this call, if any. If
                          no DMA window was created (that is, if the
                          <emphasis>Status</emphasis> is not 0), then this field is
                          present but not used.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>I/O Starting Address Hi</para>
                        </entry>
                        <entry>
                          <para>Represents the most-significant 32-bits of the starting
                          address on the I/O bus for the DMA window created by this call,
                          if any. If no DMA window was created (that is, if the
                          <emphasis>Status</emphasis> is not 0), then this field is
                          present but not used.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>I/O Starting Address Low</para>
                        </entry>
                        <entry>
                          <para>Represents the least-significant 32-bits of the starting
                          address on the I/O bus for the DMA window created by this call,
                          if any. If no DMA window was created (that is, if the
                          <emphasis>Status</emphasis> is not 0), then this field is
                          present but not used.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_49009"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
                <emphasis>ibm,create-pe-dma-window</emphasis> RTAS call must return a
                <emphasis>Status</emphasis> of 0 (Success) only if a window with the
                requested attributes is created, and must not create a new window if a
                non-0
                <emphasis>Status</emphasis> is returned.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="dbdoclet.50569332_60545">
        <title><emphasis>ibm,remove-pe-dma-window</emphasis></title>

        <para>This RTAS call allows for the removal of PE DMA windows, including
        those created with the
        <emphasis>ibm,create-pe-dma-window</emphasis> RTAS call as well as the
        default window specified by the
        <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for the PE. All
        created DMA windows will be removed by the platform, and the default DMA
        window restored, on a partition reboot, on a DR isolate operation (see
        Requirement
        <xref linkend="dbdoclet.50569332_79382" /> and
        <xref linkend="dbdoclet.50569332_72212" />), or if the last remaining DMA
        window for the PE is removed and that window is not the default DMA
        window (see Requirements
        <xref linkend="dbdoclet.50569332_40989" /> and
        <xref linkend="dbdoclet.50569332_34916" />). After removal of a DMA
        window, software needs to use the
        <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call to find out what
        resources are available to the PE for subsequent
        <emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
                implement the
                <emphasis>ibm,remove-dma-window</emphasis> call using the argument call
                buffer defined by
                <xref linkend="dbdoclet.50569332_36074" />.</para>

                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_36074">
                  <title>Argument Call Buffer
                  <emphasis>ibm,remove-pe-dma-window</emphasis></title>
                  <tgroup cols="3">
                    <colspec colname="c1" colwidth="1*" />
                    <colspec colname="c2" colwidth="2*" />
                    <colspec colname="c3" colwidth="4*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Parameter Type</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Name</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Values</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="3" valign="middle">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for
                          <emphasis>ibm,remove-pe-dma-window</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>LIOBN</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>LIOBN of the DMA window to be removed.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Parameter error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The caller
                of the
                <emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call must assure that
                the TCE table specified by the
                <emphasis>LIOBN</emphasis> field does not contain any valid mappings at
                the time of the call (that is, that the window is not being used).</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569332_40989">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
                The platform must
                restore the default DMA window for the PE on a call to the
                <emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call when all of the
                following are true:</para>

                <orderedlist numeration="loweralpha">
                  <listitem>
                    <para>The call removes the last DMA window remaining for the
                    PE.</para>
                  </listitem>

                  <listitem>
                    <para>The DMA window being removed is not the default window.</para>
                  </listitem>
                </orderedlist>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569332_34916">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
                In Requirement
                <xref linkend="dbdoclet.50569332_40989" />, the platform must provide the
                same LIOBN, location, and size as specified in the
                <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
                Device Tree for the PE.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="sec_ext_to_ddw">
        <title>Extensions to Dynamic DMA Windows</title>

        <para>Platforms supporting the DDW option implement extensions described
        in this section. These extensions include: adding the
        <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> property see
        <xref linkend="LoPAR.DeviceTree" /> to those nodes that include the
        <emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property, and
        implementing the functional extensions specified for the architectural
        level in
        <xref linkend="dbdoclet.50569332_25585" />. The
        <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> property value is a
        list of integers the first integer indicates the number of extensions
        implemented and subsequent integers, one per extension, provide a value
        associated with that extension. Thus the property value is designed to
        grow over time in such a way as to enable earlier client programs to
        ignore later firmware extensions and later client programs to operate on
        back level firmware. For this level of compatibility to work, the client
        code needs to ignore extensions beyond what were defined when the client
        code was written, and be prepared to operate on back level platforms t at
        do not implement all the extensions that were defined when the client
        code was written.</para>

        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_25585">
          <title>DDW Option Extensions</title>
          <tgroup cols="3">
            <colspec colname="c1" colwidth="33*" />
            <colspec colname="c2" colwidth="33*" />
            <colspec colname="c3" colwidth="33*" />
            <thead>
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">DDW Option LoPAR or PAPR Level</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">
                    <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> list
                    index</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Value Definition</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <para>2.7</para>
                </entry>
                <entry>
                  <para>2</para>
                </entry>
                <entry>
                  <para>Token of the i
                  <emphasis>bm,reset-pe-dma-windows</emphasis> RTAS Call</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>2.7</para>
                </entry>
                <entry>
                  <para>3</para>
                </entry>
                <entry>
                  <para>Value of 1 indicates the OS may invoke RTAS <emphasis>ibm,query-pe-dma-window</emphasis>
                  with Number Outputs equal to 6.  Other values are reserved.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_ext_to_ddw"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For compatibility with changing extensions to the Dynamic DMA
                Windows (DDW) option:</emphasis> The client program must ignore extensions
                as represented by
                <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> value list integers
                beyond those defined when the client code was written.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_ext_to_ddw"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For compatibility with changing extensions to the Dynamic DMA
                Windows (DDW) option:</emphasis> The client program must be prepared to
                operate on back level platforms that do not implement all the extensions
                that were defined when the client code was written, including no
                extensions at all.</para>
              </listitem>
         	</varlistentry>
        </variablelist>


        <section xml:id="sec_reset_pe_dma_windows">
          <title><emphasis>ibm,reset-pe-dma-windows</emphasis></title>
          <para>The
          <emphasis>ibm,reset-dma-windows</emphasis> call resets the TCE table
          allocation for the PE to its boot time value as communicated in the
          <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> OF Device Tree property
          in the for the PE.</para>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
                  IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
                  level 2.7:</emphasis> RTAS must implement the
                  <emphasis>ibm,reset-dma-windows</emphasis> call using the argument call
                  buffer defined by
                  <xref linkend="dbdoclet.50569332_68052" />.</para>

                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_68052">
                    <title>Argument Call Buffer
                    <emphasis>ibm,reset-pe-dma-windows</emphasis></title>
                    <tgroup cols="3">
                      <colspec colname="c1" colwidth="1*" />
                      <colspec colname="c2" colwidth="2*" />
                      <colspec colname="c3" colwidth="4*" />
                      <thead>
                        <row>
                          <entry>
                            <para>
                              <emphasis role="bold">Parameter Type</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Name</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Values</emphasis>
                            </para>
                          </entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry morerows="5" valign="middle">
                            <para>In</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Token</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Token for
                            </para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number Inputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>3</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number Outputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>config_addr</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>PE configuration address</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>PHB_Unit_ID_HI</para>
                          </entry>
                          <entry>
                            <para>Represents the most-significant 32-bits of the Unit ID of
                            the PHB that corresponds to the config_addr</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>PHB_Unit_ID_Low</para>
                          </entry>
                          <entry>
                            <para>Represents the least-significant 32-bits of the Unit ID
                            of the PHB that corresponds to the config_addr</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>Out</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Status</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>0: Success</para>
                            <para>-1: Hardware Error</para>
                            <para>-2: Busy, Try again later</para>
                            <para>-3: Parameter error</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
                  IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
                  level 2.7:</emphasis> The caller of the
                  <emphasis>ibm,reset-pe-dma-windows</emphasis> RTAS call must assure that
                  the TCE table(s) assigned to the PE specified by the
                  <emphasis>config_addr</emphasis> field contain no valid mappings at the
                  time of the call (that is, that the window(s) is not being used).</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
                  IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
                  level 2.7:</emphasis> On a call to
                  <emphasis>ibm,restore-pe-dma-windows</emphasis>, the platform must
                  restore the default DMA window per the values provided in the
                  <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> Tree property
                  in the for the PE (same LIOBN, location, and size).</para>
                </listitem>
           	</varlistentry>
         </variablelist>


        </section>

      </section>

    </section>

</section>