<?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.
  
-->
<chapter xmlns="http://docbook.org/ns/docbook" 
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xlink="http://www.w3.org/1999/xlink" 
         version="5.0"
         xml:id="ch_call_defn">
         
    <title>Call Function Definition</title>
    
    <para>This section specifies the semantics of all the RTAS calls. It
    specifies the RTAS function name, the contents of its argument call buffer
    (its token, input parameters, and output values) and semantics.</para>
    
    <section xml:id="dbdoclet.50569332_26944">
      <title>NVRAM Access Functions</title>
      <para>This architecture requires an area of non-volatile memory (NVRAM)
      to hold OF options, RTAS information, machine configuration state, OS
      state, diagnostic logs, etc. The type and size of NVRAM is specified in
      the OF device tree. The format of NVRAM is detailed in 
      <xref linkend="LoPAR.Platform" />.</para>
      <para>In order to give the OS the ability to access 
      NVRAM on
      different platforms that may use different implementations or locations
      for NVRAM, a layer of abstraction is provided to the OS. The functions in
      this section provide an interface for reading and writing NVRAM with byte
      level operations with no boundary requirements.</para>
    
      <section xml:id="dbdoclet.50569332_96529">
        <title><emphasis>nvram-fetch</emphasis></title>
        <para>The RTAS function 
        <emphasis>nvram-fetch</emphasis> copies data from a given offset in NVRAM
        into the user specified buffer.</para>
  
        <variablelist>
         	<varlistentry >
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_96529" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement an 
                <emphasis>nvram-fetch</emphasis> function that returns data from NVRAM
                using the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_28551" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28551">
                  <title>Argument Call Buffer 
                  <emphasis>nvram-fetch</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>nvram-fetch</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>Index</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Byte offset in NVRAM</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of data buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Size of data buffer (in bytes)</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Parameter out of range</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Num</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Number of bytes successfully copied</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_57392">
        <title><emphasis>nvram-store</emphasis></title>
        <para>The RTAS function 
        <emphasis>nvram-store</emphasis> copies data from the user specified
        buffer to a given offset in NVRAM.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57392" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement an 
                <emphasis>nvram-store</emphasis> function that stores data in NVRAM using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_28984" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28984">
                  <title>Argument Call Buffer 
                  <emphasis>nvram-store</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>nvram-store</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>Index</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Byte number in NVRAM</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of data buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Size of data buffer (in bytes)</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Parameter out of range</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Num</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Number of bytes successfully copied</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57392" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>If the 
                <emphasis>nvram-store</emphasis> operation succeeded, the contents of
                NVRAM must have been updated to the user specified values. The contents
                of NVRAM are undefined if the RTAS call failed.</para>
                <para>
                <emphasis role="bold">Platform Implementation Note:</emphasis> The platform may keep
                the NVRAM data cached in volatile memory as long as the cache is
                implemented as a store-through cache and not a store-in cache. That is,
                changed data is written to NVRAM as soon as possible. Return from the
                nvram-store call with a &#8220;success&#8221; 
                <emphasis>Status</emphasis> is permissible after placing the data into a
                store-through cache and prior to the actual writing to the NVRAM.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57392" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The caller of the 
                <emphasis>nvram-store</emphasis> RTAS call must maintain the NVRAM
                partitions as specified in 
                <xref linkend="LoPAR.Platform" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
    
    </section>
    
    <section xml:id="dbdoclet.50569332_24992">
      <title>Time of Day</title>
      <para>The minimum system requirements include a non-volatile 
      real time
      clock which maintains the time of day even if power to the machine is
      removed. Minimum requirements for this clock are described in Requirement
      
      <xref linkend="LoPAR.Platform" />.</para>
    
      <section xml:id="sec_TOD">
        <title>Time of Day Inputs/Outputs</title>
        <para>The OS maintains the clock in UTC. This allows the OS and
        diagnostics to co-exist with each other and provide uniform handling of
        time.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_TOD" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The date and time inputs and outputs to
                the RTAS time of day function calls are specified with the year as the
                actual value (for example, 1995), the month as a value in the range 1-12,
                the day as a value in the range 1-31, the hour as a value in the range
                0-23, the minute as a value in the range 0-59, and the second as a value
                in the range 0-59. The date must also be a valid date according to common
                usage: the day range being restricted for certain months, month 2 having
                29 days in leap years, etc.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_TOD" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>OSs must account for local time, for
                daylight savings time when and where appropriate, and for leap
                seconds.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_TOD" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>RTAS must account for leap years.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_88127">
        <title><emphasis>get-time-of-day</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_88127" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>get-time-of-day</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_28377" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28377">
                  <title>Argument Call Buffer 
                  <emphasis>get-time-of-day</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>get-time-of-day</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>8</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="7">
                          <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
                          below)</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Clock Busy, Try again later</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Year</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Year</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Month</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-12</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Day</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-31</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Hour</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-23</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Minute</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Second</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Nanoseconds</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-999999999</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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 again. However, software may issue
                the call again either earlier or later than this.</para>
              </listitem>
         	</varlistentry>
  
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_88127" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>RTAS must read the current time and set
                the output values to the best resolution provided by the platform.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_35194">
        <title><emphasis>set-time-of-day</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_35194" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>set-time-of-day</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_19230" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_19230">
                  <title>Argument Call Buffer 
                  <emphasis>set-time-of-day</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="9">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>set-time-of-day</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>7</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Year</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Year</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Month</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-12</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Day</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-31</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Hour</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-23</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Minute</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Second</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Nanosecond</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-999999999</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <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
                          below)</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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 again. However, software may issue
                the call again either earlier or later than this.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_35194" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>RTAS must set the time of day to the best
                resolution provided by the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_35194" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>RTAS must return a 
                <emphasis>Status</emphasis> of -3 (Parameter Error) to the 
                <emphasis>set-time-of-day</emphasis> RTAS call when the specified date is
                outside the range supported by the platform.</para>
                <para><emphasis role="bold">Software Implementation Note:</emphasis> The OS maintains the clock in UTC.
                This allows the OS and diagnostics to co-exist with each other and
                provide uniform handling of time. Refer to Requirement 
                <xref linkend="LoPAR.Platform" /> for further details on the time
                of day clock.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_13743">
        <title><emphasis>set-time-for-power-on</emphasis></title>
        <para>Some platforms provide the ability to set a time to cause the
        platform power on. The 
        <emphasis>set-time-for-power-on</emphasis> call provides the interface to
        the OS for setting this timer.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13743" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement the 
                <emphasis>set-time-for-power-on</emphasis> call using the argument call
                buffer defined by 
                <xref linkend="dbdoclet.50569332_62200" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62200">
                  <title>Argument Call Buffer
                  <emphasis>set-time-for-power-on</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="9">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>set-time-for-power-on</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>7</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Year</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Year</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Month</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-12</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Day</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1-31</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Hour</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-23</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Minute</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Second</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-59</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Nanosecond</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0-999999999</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <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
                          below)</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Clock Busy, Try again later</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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 again. However, software may issue
                the call again either earlier or later than this.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13743" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>Hardware must support power on times of
                up to four weeks into the future, at a minimum.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13743" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>RTAS must schedule the time for power on
                as close as it can approach to the desired time.</para>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> Hardware limitations on
                the duration of the power-on timer may result in power-on sooner than
                requested by software. If present in the
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node, the OF property 
                <emphasis role="bold"><literal>&#8220;power-on-max-latency&#8221;</literal></emphasis> gives in days the
                maximum power-on duration capability of the hardware. If the property is
                not present, software should expect the default of a maximum of 28 days.
                A &#8220;day&#8221; is defined as 24 hour increments from the current
                time.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13743" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If the system is in a powered down state
                at the time scheduled by 
                <emphasis>set-time-for-power-on</emphasis> (within the accuracy of the
                clock), then power must be reapplied and the system must go through its
                power on sequence.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13743" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>RTAS must return a 
                <emphasis>Status</emphasis> of -3 (Parameter Error) to the 
                <emphasis>set-time-for-power-on</emphasis> RTAS call when the specified
                date is outside the range supported by the platform (such as before
                current TOD).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>

    </section>
    
    <section xml:id="dbdoclet.50569332_16852">
      <title>Error and Event Reporting</title>
      <para>The error and event reporting RTAS calls are designed to provide an
      abstract interface into hardware registers in the system that may contain
      correctable or non-correctable errors and to provide an abstract
      interface to certain platform events that may be of interest to the OS.
      Such errors and events may be detected either by a periodic scan or by an
      exception trap.</para>
      <para>These functions are not intended to replace the normal error
      handling in the OS. Rather, they enhance the OS&#8217;s abilities by
      providing an abstract interface to check for, report, and recover from
      errors or events on the platform that are not necessarily known to the
      OS.</para>
      <para>The OS uses the error and event RTAS calls in two distinct
      ways:</para>
      
      <orderedlist>		      
        <listitem>
          <para>Periodically, the OS calls 
          <emphasis>event-scan</emphasis>
          to have the
          system firmware check for any errors or events that have occurred.</para>
        </listitem>

        <listitem>
          <para>Whenever the OS receives an interrupt or exception that it
          cannot fully process, it calls 
          <emphasis>check-exception.</emphasis>.</para>
        </listitem>
      </orderedlist>		      

      <para>The first case covers all errors and events that do not signal
      their occurrence with an interrupt or exception. The second case covers
      those errors and events that do signal with an interrupt or exception. It
      is platform dependent whether any specific error or event causes an
      interrupt on that platform.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16852" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>RTAS must return the event generated by a
              particular interrupt or event source by either 
              <emphasis>check-exception</emphasis> or 
              <emphasis>event-scan</emphasis>, but not both.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16852" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis>check-exception</emphasis> and 
              <emphasis>event-scan</emphasis>, on a 64-bit capable platform, must be
              able to handle platform resources that are accessed using 64-bit
              addresses when instantiated in 32-bit mode.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="dbdoclet.50569332_24845">
        <title><emphasis>event-scan</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement an 
                <emphasis>event-scan</emphasis>
                call using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_23686" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_23686">
                  <title>Argument Call Buffer
                  <emphasis>event-scan</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>event-scan</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>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Event Mask</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Mask of event classes to process</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Critical</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Indicates whether this call is required to complete
                          quickly</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of error log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Length of error log buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1: No Errors Found</para>
                          <para>0: New Error Log returned</para>
                          <para>-1: Hardware Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The <emphasis>event-scan</emphasis> call must fill in the error log with a
                single error log formatted as specified in 
                <xref linkend="LoPAR.Error" />. If necessary, the data placed
                into the error log must be truncated to 
                <emphasis>length</emphasis> bytes.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>RTAS must only check for errors or events
                that are within the classes defined by the 
                <emphasis>Event mask. Event mask</emphasis> is a bit mask of error and
                event classes. Refer to 
                <xref linkend="LoPAR.Error" /> for the definition of the bit
                positions.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If <emphasis>Critical</emphasis> is non-zero, then RTAS must perform only
                those operations that are required for continued operation. No extended
                error information is returned.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The <emphasis>event-scan</emphasis> call must return the first found error or
                event and clear that error or event so it is only reported once.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>The OS must continue to call 
                <emphasis>event-scan</emphasis> while a 
                <emphasis>Status</emphasis> of &#8220;New Error Log returned&#8221; is
                returned.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para>The <emphasis>event-scan</emphasis> call must be made at least 
                <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis>
                times per minute for each error and event class and
                must have the 
                <emphasis>Critical</emphasis> parameter equal to 0 for this periodic
                call.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24845" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para>The platform must not return more than
                two error logs during the first sequence of 
                <emphasis>event-scan</emphasis> RTAS calls after boot of an OS image, and
                must not return more than one error log to that OS image during any
                sequence of 
                <emphasis>event-scan</emphasis> RTAS calls after the first time a non-zero
                Status is returned.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
        
        <para>
          <emphasis role="bold">Software Implementation Notes:</emphasis>
        </para>      
        <orderedlist>		      
          <listitem>
            <para>In a multiprocessor system, each processor should call
            event-scan periodically, not always the same one. The 
            <emphasis>event-scan</emphasis> function needs to be called a total of
            <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis>
            times a minute.</para>
          </listitem>
  
          <listitem>
            <para>The maximum size of the error log is specified in the OF device
            tree as the 
            <emphasis role="bold"><literal>&#8220;rtas-error-log-max&#8221;</literal></emphasis>
            property of the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
          </listitem>
  
          <listitem>
            <para>This call does not log the error in NVRAM. It returns the error
            log to the OS. It is the responsibility of the OS to take appropriate
            action.</para>
          </listitem>
  
          <listitem>
            <para>For best system performance, the requested 
            <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis> should be as low
            as possible, and as a goal should not exceed 120 scans per minute.
            Maximum system performance is obtained when no scans are required.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="dbdoclet.50569332_71287">
        <title><emphasis>check-exception</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>check-exception</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_42307" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_42307">
                  <title>Argument Call Buffer
                  <emphasis>check-exception</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="9">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>check-exception</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>6 (without Extended Information)</para>
                          <para>7 (with Extended Information)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Vector Offset</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>The vector offset for the exception. See 
                          <emphasis>
                            <xref linkend="dbdoclet.50569387_99718" />
                          </emphasis>.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Additional Information</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Information which RTAS may need to determine the cause of
                          the exception, but which may be unavailable to it in hardware
                          registers. See 
                          <xref linkend="dbdoclet.50569332_28196" /> for details.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Event Mask</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Mask of event classes to process</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Critical</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Indicates whether this call is required to complete
                          quickly</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of error log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Length of error log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Extended Information</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>See Requirement 
                          <xref linkend="dbdoclet.50569332_40901" />.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1: No Errors Found</para>
                          <para>0: New Error Log returned</para>
                          <para>-1: Hardware Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_40901">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The OS must provide the value specified in 
                <xref linkend="dbdoclet.50569332_28196" /> in the 
                <emphasis>Additional Information</emphasis> parameter in the call to
                <emphasis>check-exception</emphasis>, with the 
                <emphasis>Number Inputs</emphasis> parameter set to 6. If the value (e.g.,
                SRR1) is too large to fit in this cell, the lower 32-bits must be
                provided here, the upper 32-bits provided in the 
                <emphasis>Extended Information</emphasis> parameter, and the 
                <emphasis>Number Inputs</emphasis> parameter set to 7.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28196">
                  <title>Additional Information Provided to
                  <emphasis>check-exception</emphasis> call</title>
                  <tgroup cols="2">
                    <colspec colname="c1" colwidth="50*" />
                    <colspec colname="c2" colwidth="50*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Source of Interrupt</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Value of &#8220;Additional
                            Information&#8221; Variable</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>External Interrupt</para>
                        </entry>
                        <entry>
                          <para>Interrupt number</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Machine check exception</para>
                        </entry>
                        <entry>
                          <para>Value of register SRR1 at entry to machine check
                          handler</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>System Reset exception</para>
                        </entry>
                        <entry>
                          <para>Value of register SRR1 at entry to system reset
                          handler</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Other exception</para>
                        </entry>
                        <entry>
                          <para>Value of register SRR1 at entry to exception
                          handler</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The <emphasis>check-exception</emphasis> call must fill in the error log with
                a single error log formatted as specified in 
                <xref linkend="LoPAR.Error" />. The data in the error log
                must be truncated to 
                <emphasis>length</emphasis> bytes.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If <emphasis>Critical</emphasis> is non-zero, then RTAS must perform only
                those operations that are required for continued operation. No extended
                error information is returned.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The <emphasis>check-exception</emphasis> call must return the first found
                error or event and clear that error or event so it is only reported
                once.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71287" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>RTAS must only check for errors or events
                that are within the classes defined by the 
                <emphasis>Event mask. Event mask</emphasis> is a bit mask of error and
                event classes. Refer to 
                <xref linkend="LoPAR.Error" /> for the definition of the bit
                positions.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
        
        <orderedlist>		      
          <listitem>
            <para>All OS reserved exception handlers should call 
            <emphasis>check-exception</emphasis> to process any errors that are
            unknown to the OS.</para>
          </listitem>
  
          <listitem>
            <para>The 
            <emphasis>interrupt number</emphasis> for external device interrupts is
            provided in the OF device tree as specified in 
            <xref linkend="LoPAR.Platform" />.</para>
          </listitem>
  
          <listitem>
            <para>Software, with knowledge of the class of event it seeks, matches
            the data in the Vector Offset, Additional Information, and Extended
            Information with the Event Mask such that ambiguity does not
            result.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="dbdoclet.50569332_71223">
        <title><emphasis>rtas-last-error</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71223" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement an 
                <emphasis>rtas-last-error</emphasis> call using the argument call buffer
                defined in 
                <xref linkend="dbdoclet.50569332_20789" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20789">
                  <title>Argument Call Buffer
                  <emphasis>rtas-last-error</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>rtas-last-error</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>Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of error log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Length of error log buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1: No Errors Found</para>
                          <para>0: New Error Log Returned</para>
                          <para>-1: Hardware Error (cannot create log)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71223" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The <emphasis>rtas-last-error</emphasis> call must fill in the error log with
                a single error log formatted as specified in 
                <xref linkend="LoPAR.Error" />. If necessary, the data placed
                into the error log must be truncated to &#8216;length&#8221;
                bytes.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_71223" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>RTAS must only check for hardware errors
                that occurred during a prior call to some other RTAS function, resulting
                in a -1 (Hardware Error) return 
                <emphasis>Status</emphasis>.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Software Note:</emphasis> This function is intended to provide
        the OS with more detailed failure information after an RTAS call returns
        with a -1 (Hardware Error) 
        <emphasis>Status</emphasis>, and should not be called except for this
        purpose. If
        <emphasis>rtas-last-error</emphasis> itself returns a -1 
        <emphasis>Status</emphasis>, then it could not create the error log data
        because of a further error, and the OS should not try to call it
        again.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_82815">
        <title>Platform Dump Option</title>
        
        <para>The architectural intent of the Platform Dump option is to allow a
        mechanism for the platform to communicate a variety of dump data used to
        debug problems within the platform firmware or hardware.</para>
      
        <section xml:id="dbdoclet.50569332_98203">
          <title><emphasis>ibm,platform-dump</emphasis></title>
          
          <para>This RTAS call is used to transfer dump data from the platform to
          the OS. It is expected that this routine will have to be called several
          times to complete the transfer of the diagnostic dump data. It is also
          anticipated that multiple dumps could be in the process of completion at
          the same time. Individual dumps are identified by a dump tag passed by
          the OS. The OS may interleave calls to 
          <emphasis>ibm,platform-dump</emphasis> with different RTAS calls. Other
          standard RTAS locking rules apply (for example, only one processor may
          call RTAS at a time).</para>
          <para>The OS only makes the 
          <emphasis>ibm,platform-dump</emphasis> RTAS call when an event scan
          returns an error log with an Event Type of &#8220;Dump
          Notification&#8221; as described in Version 6 or later of the RTAS
          General Extended Error Log Format.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> The RTAS function 
                  <emphasis>ibm,platform-dump</emphasis> must be implemented and must
                  implement the argument call buffer as defined by 
                  <xref linkend="dbdoclet.50569332_26410" />.</para>
    
                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26410">
                    <title>Argument Call Buffer 
                    <emphasis>ibm,platform-dump</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="8">
                            <para>In</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Token</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Token for 
                            <emphasis>ibm,platform-dump</emphasis></para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number of Inputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>6</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number of Outputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>5</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Dump_Tag_Hi</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Most-significant 32 bits of a Dump_Tag representing an id
                            of the dump being processed</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Dump_Tag_Lo</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Least-significant 32 bits of a Dump_Tag representing an
                            id of the dump being processed</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Sequence_Hi</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Most-significant 32 bits of the Sequence, a value
                            indicating what portion of a dump to be returned by the call.
                            Sequence of 0 returns the beginning of the Dump. The value in
                            all subsequent call as needed, should be set to the value of
                            the Next_Sequence returned from each previous call.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Sequence_Lo</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Least-significant 32 bits of the Sequence</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Buffer</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Address of dump buffer (NULL indicates completion of
                            processing)</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Length</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Length of the buffer in bytes (min. 1024)</para>
                          </entry>
                        </row>
                        <row>
                          <entry morerows="4">
                            <para>Out</para>
                          </entry>
                          <entry morerows="0">
                            <para>
                              <emphasis>Status</emphasis>
                            </para>
                          </entry>
                          <entry morerows="0">
                            <para>-1: Hardware error</para>
                            <para>-2: Busy, try again later</para>
                            <para>-9002: Not Authorized</para>
                            <para>0: Dump complete</para>
                            <para>1: Continue dump</para>
                            <para>990x: Extended Delay where x is a number 0-5</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Next_Sequence_Hi</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Most-significant 32 bits of the Next_Sequence value
                            indicating the portion of the dump to be retrieved on the next
                            call if needed. (If 
                            <emphasis>Status</emphasis> is returned as 0, then the dump is
                            complete and there is no next call required. The value of
                            Next_Sequence in this case is undefined.)</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Next_Sequence_Lo</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Least-significant 32 bits of the Next_Sequence
                            value</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Bytes_Returned_Hi</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Most-significant 32 bits of the Bytes_Returned value
                            indicating the number of valid bytes returned in the
                            Buffer</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Bytes_Returned_Lo</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Least-significant 32 bits of the Bytes_Returned value
                            indicating the number of valid bytes returned in the
                            Buffer</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                  <para>
                  <emphasis role="bold">Software Implementation Note:</emphasis> 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,platform-dump</emphasis> again. However, software may issue
                  the 
                  <emphasis>ibm,platform-dump</emphasis> call again either earlier or later
                  than this.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> On the first call to 
                  <emphasis>ibm,platform-dump</emphasis> of a platform dump sequence for a
                  given Dump_Tag, the Sequence value must be initialized to zero and on
                  subsequent calls for the same tag, the Dump_Sequence must be set to
                  Next_Sequence of the previous call made with the same Dump_Tag or else
                  set to zero to restart the entire dump sequence.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> The dump tag passed to
                  any call to ibm,platform-dump must be a value specified by the platform
                  and communicated to the OS by an 
                  <emphasis>event-scan</emphasis> error log entry.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> Once a 
                  <emphasis>Status</emphasis> of 0 (Dump complete) or -1 (Hardware
                  error&#8221; is returned for the 
                  <emphasis>ibm,platform-dump</emphasis> call with a particular dump tag,
                  the dump is considered complete from a platform standpoint, but for the
                  &#8220;Dump complete&#8221; case the OS must signal to the platform that
                  the processing of the dump has been completed by a final call for the
                  Dump_Tag with the Buffer address set to NULL.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> If at any time a
                  partition receives a -9002, Not Authorized, return code for an 
                  <emphasis>ibm,platform-dump</emphasis> RTAS, the partition must cease
                  attempting to acquire the dump information it was in process of acquiring
                  and discard any portion already acquired.</para>
                  <para>
                  <emphasis role="bold">Programming Note:</emphasis> It is expected that a platform
                  generally only transmits a dump to a single partition. However, the above
                  requirement makes provision for the platform abandoning the transmission
                  of a dump to a partition after it has been initiated, presumably to
                  re-initiate transmission to a different partition or to a Hardware
                  Management Console (HMC).</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> The contents of dump
                  information returned through the sequence of calls to 
                  <emphasis>ibm,platform-dump</emphasis>, must follow a dump directory
                  structure as defined in 
                  <xref linkend="dbdoclet.50569332_43488" />.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_98203" 
              xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Platform Dump option:</emphasis> Collectively the dump
                  data returned from a sequence of 
                  <emphasis>ibm,platform-dump</emphasis> calls for a given Dump_tag must
                  consist of one dump file directory entry as described in 
                  <xref linkend="dbdoclet.50569332_35075" /> followed by one or more dump
                  section directory entries as described in 
                  <xref linkend="dbdoclet.50569332_69092" /> followed by a dump data section
                  for each dump section directory entry earlier included.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para>
            <emphasis role="bold">Programming Notes:</emphasis>
          </para>
          
          <orderedlist>		      
            <listitem>
              <para>As required in 
              <xref linkend="dbdoclet.50569332_72712" />, the OS can determine the
              maximum size of a copy of each dump that can be returned by issuing an 
              <emphasis>ibm,get-system-parameter</emphasis> for the
              platform-dump-max-size. In addition, in the case of any change in the
              value of this parameter, the platform may generate a Platform Event Log
              entry announcing the change in the maximum size, and specifying the new
              size in the IO Events Section. This entry, when generated, is then
              returned by the 
              <emphasis>event-scan</emphasis> RTAS call.</para>
            </listitem>
    
            <listitem>
              <para>The Dump_Tag is taken from the Dump Locator Section of the
              Platform Error/Event Log Format, Version 6 or later. Specifically,
              Dump_Tag_Hi is composed of the 8 bit Dump Type as found in the Dump
              Locator Section, padded with 24 bits on the left to make a 32 bit
              quantity. The Dump_Tag_Lo is the Dump ID found in the Dump Locator
              Section of the Error log entry.</para>
            </listitem>
    
            <listitem>
              <para>If the 
              <emphasis>ibm,platform-dump</emphasis> RTAS routine returns with the 
              <emphasis>Status</emphasis> of 1 (Continue dump), the transfer is
              proceeding but had to be suspended to maintain the short execution time
              requirement of RTAS routines or because more data was available than the
              Buffer could contain.</para>
            </listitem>
    
            <listitem>
              <para>The Bytes_Returned value indicates how many bytes of dump data
              (if any) were returned on a call and OS must be prepared to handle the
              case of no bytes returned. When Continue dump 
              <emphasis>Status</emphasis> (1) is returned, this indicates that there is
              more dump data available then was returned in the buffer. A subsequent
              call with the same Dump_tag and the Sequence value being set to the
              Next_Sequence returned from the previous call returns additional dump
              data.</para>
            </listitem>
    
            <listitem>
              <para>When a dump has been successfully transmitted, the 
              <emphasis>Status</emphasis> of 0 (Dump complete) is returned. If there is
              a hardware error preventing a dump from being successfully transmitted,
              as 
              <emphasis>Status</emphasis> of -1 (Hardware error) is returned. In either
              case, the Dump sequence is completed. It should be noted that the final
              Next_Sequence value returned is undefined. After the sequence is
              completed, the OS should make one final call for the given Dump_Tag using
              a NULL buffer pointer. (The value of the Sequence parameter for this call
              is undefined although it is acceptable for the platform to make the value
              equal to the last Next_Sequence value returned.) This call tells the
              platform that the OS has completed processing of the dump and will not
              attempt to restart the sequence.</para>
            </listitem>
    
            <listitem>
              <para>If the platform used system memory to hold dump data, the
              platform at this point is permitted to free the associated logical memory
              blocks (LMBs) reserved for the dump. Successful return from the 
              <emphasis>ibm,platform-dump</emphasis> RTAS call with a NULL buffer
              pointer indicates to the OS that one or more logical memory blocks (LMBs)
              may now be acquired by the OS. A get-sensor-state RTAS call for these
              LMBs returns with a state of &#8220;DR entity available for recovery
              (4)&#8221; after the successful return from this 
              <emphasis>ibm,platform-dump</emphasis> RTAS call.</para>
            </listitem>
    
            <listitem>
              <para>If a platform does not receive the NULL buffer pointer call dump
              for a given Dump_Tag but subsequently boots the partition, the platform
              may report the presence of the dump again on an e
              <emphasis>vent-scan</emphasis> after the boot.</para>
            </listitem>
          </orderedlist>		      
          
        </section>
        
        <section xml:id="dbdoclet.50569332_43488">
          <title>Platform Dump Directory Structure</title>
          
          <para>The entire dump contents returned over a sequence of 
          <emphasis>ibm,platform-dump</emphasis> RTAS calls for a given Dump_Tag
          follows a directory/data structure as illustrated in 
          <xref linkend="dbdoclet.50569332_35075" /> and 
          <xref linkend="dbdoclet.50569332_69092" /> where a dump consists of one
          File Directory Entry, one or more Section Directory Entries and one data
          section for each Section Directory entry.</para>
    
          <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_35075">
            <title>Platform Dump File Directory Entry Format</title>
            <tgroup cols="4">
              <colspec colname="c1" colwidth="25*" />
              <colspec colname="c2" colwidth="25*" />
              <colspec colname="c3" colwidth="25*" />
              <colspec colname="c4" colwidth="25*" />
              <thead>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Field Name</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Length</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Values</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Discussion</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>Entry Header</para>
                  </entry>
                  <entry>
                    <para>8 Bytes</para>
                  </entry>
                  <entry>
                    <para>&#8220;FILE&#8221;</para>
                  </entry>
                  <entry>
                    <para>Identifies the type of entry that follows. The value is
                    ASCII consisting of the characters &#8220;FILE&#8221; and 4
                    ASCII blanks.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Entry Length</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>Number of bytes of the entire file directory entry</para>
                  </entry>
                  <entry>
                    <para>This length includes the Entry Header and Entry Length
                    fields.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                  <entry>
                    <para>6 Bytes</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Flags</para>
                  </entry>
                  <entry>
                    <para>4 Bytes</para>
                  </entry>
                  <entry>
                    <para>See 
                    <xref linkend="dbdoclet.50569332_24173" />.</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Entry Type</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>0x0001</para>
                  </entry>
                  <entry>
                    <para>0x0001signifies a file entry.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Prefix Length</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>Number of bytes of the Dump File Base Name that is
                    considered to be a prefix.</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Dump File Base Name</para>
                  </entry>
                  <entry>
                    <para>Length in bytes computed as &#8220;Entry length&#8221; -
                    24, but not to exceed 46 characters including the ASCII NULL
                    string termination.</para>
                  </entry>
                  <entry>
                    <para>NULL terminated ASCII String consisting of ASCII
                    characters in the ranges of a-z, A-Z, 0-9, and the ASCII
                    &#8220;.&#8221;</para>
                  </entry>
                  <entry>
                    <para>Gives a base name for the dump file to be created from
                    the dump data. This base name is composed of a prefix followed
                    by additional data (e.g. dumptype.serialnumber.dumpID.timestamp
                    where dumptype.serialnumber is the prefix)</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
    
          <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_69092">
            <title>Dump Section Directory Entry Format</title>
            <tgroup cols="4">
              <colspec colname="c1" colwidth="25*" />
              <colspec colname="c2" colwidth="25*" />
              <colspec colname="c3" colwidth="25*" />
              <colspec colname="c4" colwidth="25*" />
              <thead>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Field Name</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Length</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Values</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Discussion</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>Entry Header</para>
                  </entry>
                  <entry>
                    <para>8 Bytes</para>
                  </entry>
                  <entry>
                    <para>&#8220;SECTION&#8221;</para>
                  </entry>
                  <entry>
                    <para>Identifies the type of entry that follows. The value is
                    ASCII consisting of the characters &#8220;SECTION&#8221; and 1
                    ASCII blank.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Entry Length</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>Number of bytes of the entire section directory
                    entry</para>
                  </entry>
                  <entry>
                    <para>This length includes the Entry Header and Entry Length
                    fields.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Priority</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>Unsigned integer</para>
                  </entry>
                  <entry>
                    <para>See programming note after 
                    <xref linkend="dbdoclet.50569332_24173" />.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                  <entry>
                    <para>4 Bytes</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Flags</para>
                  </entry>
                  <entry>
                    <para>4 Bytes</para>
                  </entry>
                  <entry>
                    <para>See 
                    <xref linkend="dbdoclet.50569332_24173" />.</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Entry Type</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>0x0002</para>
                  </entry>
                  <entry>
                    <para>0x0002 signifies a section entry.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                  <entry>
                    <para>2 Bytes</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Section Length</para>
                  </entry>
                  <entry>
                    <para>8 Bytes</para>
                  </entry>
                  <entry>
                    <para>Length in bytes of the section of the dump that this
                    entry is the directory for</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Section Name</para>
                  </entry>
                  <entry>
                    <para>Length in bytes computed as &#8220;Entry length&#8221; -
                    32, but not to exceed 46 characters including the ASCII NULL
                    string termination.</para>
                  </entry>
                  <entry>
                    <para>NULL terminated ASCII String.</para>
                  </entry>
                  <entry>
                    <para>Gives a name to the dump section for which this entry is
                    a directory.</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <para>The two previous tables refer to a set of flags used to describe
          information related to a dump section. The options are stored in a single
          32 bit value which is the bit-wise OR'ing of each option value defined in
          
          <xref linkend="dbdoclet.50569332_24173" />.</para>
    
          <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24173">
            <title>Dump File Format Directory Options</title>
            <tgroup cols="4">
              <colspec colname="c1" colwidth="25*" />
              <colspec colname="c2" colwidth="25*" />
              <colspec colname="c3" colwidth="25*" />
              <colspec colname="c4" colwidth="25*" />
              <thead>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Name</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Bit Position(s) of Option</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Definition</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Discussion</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>last_flag</para>
                  </entry>
                  <entry>
                    <para>0x00000001</para>
                  </entry>
                  <entry>
                    <para>Binary value set to 1 if the last directory entry.</para>
                  </entry>
                  <entry>
                    <para>Flag is never set for the File Directory entry since at
                    least one Section Directory entry follows.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>not_transmitted</para>
                  </entry>
                  <entry>
                    <para>0x00000002</para>
                  </entry>
                  <entry>
                    <para>If set to 1, indicates that the data for the block has
                    not been transmitted during some process of dump
                    transfer.</para>
                  </entry>
                  <entry>
                    <para>Platform always sets this value to 0. The bit may be set
                    to 1 by applications transmitting a dump. See Software
                    implementation note item 2: in this section below.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                  <entry>
                    <para>All but bit positions shown above</para>
                  </entry>
                  <entry>
                    <para>All other values reserved</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <para>
            <emphasis role="bold">Software Implementation Notes:</emphasis>
          </para>
          
          <orderedlist>		      
            <listitem>
              <para>Platforms supporting the 
              <emphasis>ibm,platform-dump</emphasis> call may have several unique dump
              types. All dumps of the same type on a partition have the same
              &#8220;prefix&#8221; to the name of the dump file as indicated in the
              dump file directory entry in an error log.</para>
            </listitem>
    
            <listitem>
              <para>The priority in the priority field of the section directory
              entries allow an application transmitting a dump to a remote support
              center to decide what sections of data to transmit when the connection
              bandwidth is limited. Zero is the highest priority. All sections at the
              same priority shall be transmitted if any at that priority are
              transmitted. It is intended that all directory entries be transmitted
              with the section length set to zero and their not_transmitted Dump File
              Format Directory Options flag set to a 1 if the section data cannot be
              transmitted.</para>
            </listitem>
          </orderedlist>		      
          
        </section>

      </section>

    </section>
        
    <section xml:id="dbdoclet.50569332_14852">
      <title>PCI Configuration Space</title>
      <para>Device drivers and system software need access to 
      PCI
      configuration space. 
      <xref linkend="LoPAR.Platform" /> section on "Address Map" defines
      system address spaces for PCI memory and PCI I/O spaces. It does not
      define an address space for PCI configuration. Different PCI bridges may
      implement the mechanisms for accessing PCI configuration space in
      different ways. The RTAS calls in this section provide an abstract way of
      reading and writing PCI configuration spaces.</para>
      <para>The PCI access functions take a 
      <emphasis>config_addr</emphasis> input parameter which is similar to the
      Type 1 PCI configuration space address. For conventional PCI and PCI-X
      Mode 1, this address is a 24-bit quantity composed of bus, device,
      function, and register numbers. This allows the configuration of up to
      256 buses (including sub-bridges), 32 IOAs per bus, 8 functions per IOA,
      and 256 bytes of register space per function. PCI-X Mode 2 and PCI
      Express define an extended configuration space with an additional 4-bit
      quantity which specifies an extended register number allowing for 4096
      bytes of register space per function. Refer to the 
      <xref linkend="dbdoclet.50569387_26550" /> or the 
      <xref linkend="dbdoclet.50569387_66784" /> for more details. The
      config_addr for an IOA is derived from the OF device tree, and is defined
      in 
      <xref linkend="dbdoclet.50569332_36386" />.</para>
      <para>The 
      <emphasis>ibm,read-pci-config</emphasis> and 
      <emphasis>ibm,write-pci-config</emphasis> RTAS calls allow for the
      specification of the PHB Bus Unit ID, and therefore allow for up to 256
      unique 
      <emphasis>config_addr</emphasis> bus numbers per PHB. Note that for each
      pci connector, there may be multiple PCI bus numbers, because plug-in PCI
      cards may contain PCI to PCI bridges, which create other PCI
      buses.</para>
      <para>The 
      <emphasis>PCI Local Bus Specification</emphasis> requires that
      unimplemented or reserved register space read as 0&#8217;s, and that
      reads of the Vendor ID register of IOAs or functions which aren&#8217;t
      present should be unambiguously reported (reading 0xFFFF is sufficient).
      Writes to unimplemented or reserved register space are specified as
      no-ops. Writes to IOAs or functions which aren&#8217;t present are
      undefined. These operations are undefined if a bus is specified which
      doesn&#8217;t exist.</para>

      <variablelist>
       	<varlistentry xml:id="dbdoclet.50569332_13648">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14852" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>For the RTAS PCI
              configuration space and EEH functions where the parameter 
              <emphasis>config_addr</emphasis> is requested as input, the 
              <emphasis>config_addr</emphasis> parameter must be as specified by the hi
              cell of the physical address in Open Firmware Working Group proposal
              number 516 Ver 1.8 (see 
              <xref linkend="dbdoclet.50569332_36386" />), with the upper register
              address bits added for PCI-X Mode 2 and PCI Express, in order to access
              past the first 256 bytes of configuration space.</para>

              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_36386">
                <title>Definition 
                <emphasis>Config_addr</emphasis></title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Bit</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Definition</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>0:3</para>
                      </entry>
                      <entry>
                        <para>Upper bits of the Register Number, when applicable,
                        otherwise 0. Set to 0 when the PCI extended configuration space
                        is not available, due to lack of support somewhere from the PHB
                        to the IOA. When a value of this field can be something other
                        than 0, the 
                        <emphasis role="bold"><literal>
                        &#8220;ibm,pci-config-space-type&#8221;</literal></emphasis> property will
                        exist in the IOA's node with a value indicating that the
                        extended space is supported.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>4:7</para>
                      </entry>
                      <entry>
                        <para>Reserved (set to 0)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>8:15</para>
                      </entry>
                      <entry>
                        <para>Bus Number</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>16:20</para>
                      </entry>
                      <entry>
                        <para>Device Number</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>21:23</para>
                      </entry>
                      <entry>
                        <para>Function Number, when applicable, otherwise 0</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>24:31</para>
                      </entry>
                      <entry>
                        <para>Lower bits of the Register Number, when applicable,
                        otherwise 0</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14852" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para>All RTAS PCI Read/Write functions must
              follow the appropriate PCI specification.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14852" 
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>RTAS must follow the rules of 
              <xref linkend="LoPAR.Platform" /> when accessing PCI
              configuration space.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <para>
        <emphasis role="bold">Software Implementation Notes:</emphasis>
      </para>

      <orderedlist>		      
        <listitem>
          <para>Since PCI Configuration space is defined to be Little-Endian,
          RTAS accesses this area using the byte-reversed forms of the 
          <emphasis>Load</emphasis> and 
          <emphasis>Store</emphasis> instructions. In this fashion, the values
          passed are defined Big-Endian.</para>
        </listitem>

        <listitem>
          <para>Prior to accessing the extended configuration address space of
          PCI-X Mode 2 and PCI Express devices, an IOA device driver is responsible
          for checking if the 
          <emphasis role="bold"><literal>&#8220;ibm,pci-config-space-type&#8221;</literal></emphasis> property (see
          <xref linkend="LoPAR.DeviceTree" />) of the IOA's node exists and
          is set to a non-zero value.</para>
        </listitem>
      </orderedlist>		      

      <section xml:id="dbdoclet.50569332_59536">
        <title><emphasis>ibm,read-pci-config</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_59536" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
               <para><emphasis role="bold">For Platforms which may have greater than 256 PCI
                Buses:</emphasis> RTAS must implement an 
                <emphasis>ibm,read-pci-config</emphasis>
                call using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_28668" />.</para>
  
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28668">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,read-pci-config</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,read-pci-config</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Configuration Space Address</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>
                            <emphasis>Size</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Size of Configuration Cycle in bytes, value can be 1, 2,
                          or 4</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <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>
                            <emphasis>Value</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Value Read from the location specified by the PHB Unit ID
                          and config_addr</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_59536" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,read-pci-config</emphasis> call must return the value from
                the configuration register which is at the location specified by the PHB
                Unit ID and 
                <emphasis>config_addr</emphasis> in PCI configuration space.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_59536" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,read-pci-config</emphasis> call must perform a 1-byte,
                2-byte, or 4-byte configuration space read depending on the value of the 
                <emphasis>size</emphasis> input argument.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_59536" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>config_addr</emphasis> must be aligned to a 2-byte boundary if 
                <emphasis>size</emphasis> is 2 and to a 4-byte boundary if 
                <emphasis>size</emphasis> is 4.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_59536" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,read-pci-config</emphasis> call
                of IOAs or functions which are not present or which
                are not available to the caller must return 
                <emphasis>Success</emphasis> with all ones as the output 
                <emphasis>value</emphasis>.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_54555">
        <title><emphasis>ibm,write-pci-config</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For Platforms which may have greater than 256 PCI
                Buses:</emphasis> RTAS must implement an 
                <emphasis>ibm,write-pci-config</emphasis>
                call
                using the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_14382" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14382">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,write-pci-config</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,write-pci-config</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>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Configuration Space Address</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>
                            <emphasis>Size</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Size of Configuration Cycle</para>
                          <para>in bytes,</para>
                          <para>can be 1, 2, or 4</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Value</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Value to be written to the location specified by the PHB
                          Unit ID and 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>-3: Parameter or device enablement error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The
                <emphasis>ibm,write-pci-config</emphasis> call must store the value to the
                configuration register which is at the location specified by the PHB Unit
                ID and 
                <emphasis>config_addr</emphasis> in PCI configuration space.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,write-pci-config</emphasis> call must perform a 1-byte,
                2-byte, or 4-byte configuration space write depending on the value of the             
                <emphasis>size</emphasis> input argument.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>config_addr</emphasis> must be aligned to a 2-byte boundary if 
                <emphasis>size</emphasis> is 2 and to a 4-byte boundary if 
                <emphasis>size</emphasis> is 4.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,write-pci-config</emphasis> call
                of IOAs or functions which are not present or which
                are not available to the caller must be ignored and a 
                <emphasis>Status</emphasis> of 0 (Success) must be returned.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_10812">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_54555" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The 
                <emphasis>Status</emphasis> of -3 (Parameter or device enablement error)
                must be returned if all the following are true:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The OS attempts an 
                    <emphasis>ibm,write-pci-config</emphasis> to enable Memory or I/O for an
                    IOA, without first calling 
                    <emphasis>ibm,set-eeh-option</emphasis> to enable EEH for the IOA</para>
                  </listitem>
          
                  <listitem>
                    <para>Enabling the IOA could expose other partitions to errors from
                    the partition which is enabling the IOA</para>
                  </listitem>
          
                  <listitem xml:id="dbdoclet.50569332_45638">
                    <para>The hypervisor is
                    enforcing EEH mode</para>
                  </listitem>
                </orderedlist>		      
                
                <para>
                <emphasis role="bold">Platform Implementation Note:</emphasis> In Requirement 
                <xref linkend="dbdoclet.50569332_10812"  xrefstyle="select: nopage"/>
                <xref linkend="dbdoclet.50569332_45638"  xrefstyle="select: labelnumber"/>, 
                cross-partition errors could
                be caused due to error domains which are shared between the partitions.
                However, it is acceptable to share error domains when the IOA and its
                device driver and the partition's OS cannot (through error or
                maliciously) cause errors which affect another partition.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>
  
      </section>
      
    <section>
      <title>Operator Interfaces and Platform Control</title>
      <para>The RTAS operator interface and platform control functions provide
      the OS with the ability to perform platform services in a portable
      manner. The RTAS operator interface provides the ability for the OS to
      notify the user about OS events during boot, to notify the user of
      abnormal events, and to obtain information from the platform. The
      platform control functions give the OS the ability to obtain
      platform-specific information and to control platform features.</para>
      <para>These calls are all &#8220;best effort&#8221; calls. RTAS should
      make its best effort to implement the intent of the call. If the Platform
      Hardware does not implement some optional feature, it is permitted for
      RTAS to either return an error, or to virtualize the service in some way
      and return &#8220;Operation Succeeded.&#8221;</para>
      <para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
      
      <orderedlist>		      
        <listitem>
          <para>For example, a keyswitch
          could be virtualized by storing a keyswitch value in
          NVRAM and by providing a user interface to modify this value. The RTAS
          call 
          <emphasis>get-sensor-state</emphasis> on the 
          <emphasis>keyswitch</emphasis> returns the value stored in NVRAM.</para>
        </listitem>

        <listitem>
           <para>If these services are only called prior to the use of any of the
          underlying devices by the OS, for example, during boot time, or only
          after the OS has finished using the devices, for example, during a crash,
          then the OS can avoid mutual exclusion and sharing concerns. Otherwise,
          synchronization per 
          <xref linkend="dbdoclet.50569332_85757" />, must be performed.</para>
       </listitem>
      </orderedlist>		      

      <section xml:id="dbdoclet.50569332_33245">
        <title>Op Panel Display</title>
  
        <variablelist>
         	<varlistentry xml:id="dbdoclet.50569332_24645">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_33245" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">Platform Implementation:</emphasis>
                All servers must
                implement an operator panel display mechanism by supporting the
                <emphasis>display-character</emphasis> RTAS call.</para>
                <para>
                <emphasis role="bold">Implementation Note:</emphasis> The operator display mechanism
                in Requirement 
                <xref linkend="dbdoclet.50569332_24645" /> may be a physical alphanumeric
                display with a special purpose LCD device marked &#8220;used by
                RTAS&#8221;, or it may be some other virtualized display which is
                accessible through some method not defined by this architecture.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_33245" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">Platform Implementation:</emphasis> Servers which provide
                <emphasis>display-character</emphasis> must provide a line length of at
                least 16 characters.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
          <emphasis role="bold">Software Implementation Notes:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>There are currently four uses for the op panel display. The
            first is for display of an error code, if needed, from the
            Built-In-Self-Test (BIST) or Power-On-Self-Test (POST). This display is
            machine dependent. (These tests are executed prior to loading the OS or
            the operation of OF. Any display requirements are handled within the
            hardware.) The second is for progress indication during initialization
            and boot. This display is four digits and is updated as boot proceeds.
            The third is for display after a failure running diagnostics. In this
            case, a service request number (SRN) is displayed along with a FRU
            location code list of possible devices needing service. These numbers and
            locations can be longer than four characters. The SRN may be over 12
            characters and a FRU location code list is one or more items, typically
            three, of 2 to 32 characters. The fourth is a crash code from the OS
            which is 12 characters indicating cause and dump status.</para>
          </listitem>
  
          <listitem>
            <para>The RTAS
            <emphasis>set-indicator</emphasis> call with token #6 specifies 4 hex
            digits. The 
            <emphasis>display-character</emphasis> call requires a minimum display
            size of one line of 4 characters, but a larger display may be made known
            to the OS using the &#8220;ibm,&#8221; extension properties defined in 
            <xref linkend="dbdoclet.50569332_10053" />. When the message to be
            displayed is larger than the OS believes the display to be, the OS should
            perform appropriate truncation, scrolling, or otherwise meaningfully
            display the message using the platform&#8217;s display resource.</para>
          </listitem>
  
          <listitem>
            <para>Some servers implement a display larger than the default. For
            these servers, the 
            <emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis> property and
            the 
            <emphasis role="bold"><literal>&#8220;ibm,display-number-of-lines&#8221;</literal></emphasis> property
            are set appropriately.</para>
          </listitem>
  
          <listitem>
            <para>If the OS assumes the default display, the 2X16 display still
            works. It appears to be working in the bottom line and scrolling through
            the top line as long as only CR and LF are issued for control. The OF
            device tree properties indicate what is supported.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section>
        <title>Service Processor</title>
        <para>A service processor is not a platform requirement. Larger servers
        tend to be implemented with service processors. When implemented, the
        service processor is not seen directly as a device by software. All of
        its services which are visible to the OS, are abstracted with RTAS. The
        service processor may support the operator panel, manage sensors and
        indicators, run diagnostics, monitor the platform environment and save
        error logs. There is clearly an interface between RTAS and the service
        processor, but that interface is not intended to be used by the
        OS.</para>
        <para>The service processor, in those platforms which choose to use one,
        is key in the initialization of the platform and has interfaces with the
        OF code. It is also involved with VPD collection and NVRAM access during
        initialization. It can also provide a serial port for a remote service
        capability. The service processor is also a significantly slower
        processor than the primary PA processor. Therefore, in the implementation
        of RTAS functions which use the service processor, care should be taken
        to avoid interlocks with the service processor which could significantly
        impair performance.</para>
      
        <section xml:id="dbdoclet.50569332_60143">
          <title>Surveillance</title>
          <para>Platforms which include a service processor have the needed
          mechanism for a surveillance function; that is, the OS and the service
          processor can monitor each other. For example, if the OS crashes or
          hangs, or if the service processor has failures, a failure notification
          could occur. Notification could also occur if the platform fails during
          the boot process, or if it cannot complete a boot successfully. The
          notification can be sent to a service center or to a customer
          administrator, as determined by the customer setup of configuration
          parameters. The firmware provides notification to the OS by reporting
          exceptions through 
          <emphasis>event-scan.</emphasis> The service processor can provide
          dial-out notification if the OS stops, or if a boot process fails.</para>
          <para>In the implementation of surveillance, the service processor
          monitors the OS by tracking the issuance of heartbeats generated by calls
          to the 
          <emphasis>event-scan</emphasis> RTAS service. If a service processor
          time-out occurs prior to receiving another heartbeat, an action based on
          user defined call out policy occurs. This action could be to reboot, call
          service or power-down. The policy may be different depending on whether
          the time-out occurs during a boot process or during a period of normal OS
          operation. The default policy and time-out period, kept in NVRAM, can be
          changed from a service processor menu or from software. The platform can
          be configured such that surveillance is either enabled or disabled
          immediately after boot. After boot, temporary changes to the surveillance
          state can be made by issuing a 
          <emphasis>set-indicator</emphasis> call to indicator 9000 (see 
          <xref linkend="dbdoclet.50569332_32164" />).</para>
          <para>The following system parameters define the default behavior of
          surveillance mode (see also, 
          <xref linkend="dbdoclet.50569332_59020" /> for more information about
          these parameters and for their default values).</para>
    
          <itemizedlist>		      
            <listitem>
              <para>The 
              <emphasis role="bold"><literal>sp-sen</literal></emphasis> system parameter defines whether the default
              state of surveillance by the service processor is enabled (=on) or
              disabled (=off).</para>
            </listitem>
            
            <listitem>
              <para>The 
              <emphasis role="bold"><literal>sp-sti</literal></emphasis> system parameter defines the period of time
              (1-255 minutes) that the service processor should wait between heartbeats
              from 
              <emphasis>event-scan</emphasis>. If the time-out period expires without
              the service processor receiving another heartbeat, the service processor
              initiates recovery and reporting actions as defined by the user.</para>
            </listitem>
            
            <listitem>
              <para>The 
              <emphasis role="bold"><literal>sp-sdel</literal></emphasis> system parameter defines the period of time
              (1-120 minutes) that the service processor should wait before starting
              surveillance after control passes to the OS. This value is set to allow
              enough time for the OS to boot and initialize to the point where it can
              start calling 
              <emphasis>event-scan</emphasis> on a regular periodic basis.</para>
            </listitem>
          </itemizedlist>		      
          
          <para>
          <emphasis>Architecture Note</emphasis>: Surveillance times out if the
          time of the parameter, 
          <emphasis role="bold"><literal>sp-sdel</literal></emphasis>, plus the time of the parameter, 
          <emphasis>sp-sti,</emphasis> passes prior to receiving the first
          heartbeat. In effect, the first 
          <emphasis>event-scan</emphasis> can be considered the signal for boot
          complete.</para>
          <para>The platform may perform surveillance on the service processor
          using 
          <emphasis>event-scan</emphasis> to trigger checking as well as for
          reporting any errors found.</para>
          <para><emphasis role="bold">Software Implementation Note:</emphasis>
          The surveillance here is for keeping
          an eye on the overall functioning of the OS. If a specific process gets
          hung and the OS is still functioning, it is the responsibility of the OS
          to detect and not the surveillance discussed here.</para>
          <para><emphasis role="bold">OF Implementation Note:</emphasis>
          The OS is expected to call the 
          <emphasis>event-scan</emphasis> RTAS service (with the internal-errors
          mask bit on) at the rate defined by the property 
          <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis> in the OF device
          tree. If an 
          <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis>
          of zero (0)
          is placed in the OF device tree and surveillance is initialized as
          &#8216;active&#8217;, a surveillance time-out occurs after the time-out
          period since the heartbeats are triggered by the 
          <emphasis>event-scan</emphasis> call. If there is reason to operate with
          the rate = 0, the default state of surveillance (
          <emphasis role="bold"><literal>sp-sen</literal></emphasis> parameter in NVRAM) should be disabled, and
          the surveillance sensor and indicator should not be placed in the OF
          device tree.</para>
    
          <variablelist>
           	<varlistentry xml:id="dbdoclet.50569332_41318">
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60143" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">Platform Implementation:</emphasis> The default surveillance
                  policy must be defined by the
                  <emphasis role="bold"><literal>sp-sen</literal></emphasis>, 
                  <emphasis role="bold"><literal>sp-sti</literal></emphasis> and 
                  <emphasis role="bold"><literal>sp-sdel</literal></emphasis> system parameters, as set by the service
                  processor or by software.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60143" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">Platform Implementation:</emphasis> Heartbeats to the service
                  processor must only be sent as the result of a call to the
                  <emphasis>event-scan</emphasis> RTAS service with the
                  <emphasis>internal-errors</emphasis> bit (bit 0) set to 1 in the call
                  buffer 
                  <emphasis>Event Mask</emphasis> parameter.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry xml:id="dbdoclet.50569332_32879">
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60143" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">Platform Implementation:</emphasis> In platforms which implement
                  surveillance, the 
                  <emphasis>event-scan</emphasis> RTAS service may be called more than once
                  per minute, but the heartbeat to the service processor must be sent at
                  the rate of at least once per minute.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry xml:id="dbdoclet.50569332_67400">
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60143" 
              xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">Platform Implementation:</emphasis> In platforms which implement
                  surveillance, the 
                  <emphasis>ibm,os-term</emphasis> RTAS call must be implemented.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para>
          <emphasis role="bold">Software Note:</emphasis> Requirement 
          <xref linkend="dbdoclet.50569332_67400" /> provides a mechanism for the OS
          to release control of the platform without being aware of the state of
          surveillance. With the definition of a default platform state for
          surveillance, the OS may not be aware of the function, yet surveillance
          may be used. Platforms may not have a dependency on the OS to turn off
          surveillance during normal shutdown (a shutdown not including immediate
          reboot).</para>
        </section>
        
        <section xml:id="sec_surv_smp_sys">
          <title>Surveillance on SMP Systems</title>
          <para>Each running processor in an SMP system should be covered by
          surveillance. The following requirements assure this coverage.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_surv_smp_sys" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para>Each processor which is running, that
                  is, not stopped by the stop-self RTAS call or not stopped due to BIST
                  testing at bring-up, must issue the event-scan RTAS call. The rate of
                  issue is the 
                  <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis> times per minute
                  divided by the number of processors. This is the minimum rate.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_surv_smp_sys" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para>The system must allow for all
                  processors to cycle through their event-scan calls. The timeout period
                  for a surveillance event, which is 
                  <emphasis role="bold"><literal>sp-sti</literal></emphasis>, must be greater than n time t, where n is
                  the number of processors and t is the 
                  <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis>.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_surv_smp_sys" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para>The surveillance event must be signaled
                  if after the surveillance interval, 
                  <emphasis>sp-sti,</emphasis> one or more processors has not issued an
                  event-scan call.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para>
          <emphasis role="bold">Implementation Note:</emphasis> Care is required in the
          assignment of the surveillance interval and the 
          <emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis> such that a
          surveillance event is not signaled prematurely. The default values are
          not meant for a system with a large number of processors.</para>
        </section>

      </section>
      
      <section xml:id="dbdoclet.50569332_10053">
        <title><emphasis>display-character</emphasis></title>
        <para>The 
        <emphasis>display-character</emphasis> function allows the display of both
        alphabetic and numeric information. The display for this function
        requires at least one line of four (4) characters. Also specified are the
        control characters carriage-return (CR) (0x0D) and line-feed (LF)
        (0x0A).</para>
        <para>The following OF properties are defined in 
        <xref linkend="LoPAR.DeviceTree" />:</para>
        
        <itemizedlist>		      
          <listitem>
            <para><emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis role="bold"><literal>&#8220;ibm,display-number-of-lines&#8221;</literal></emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis role="bold"><literal>&#8220;ibm,form-feed&#8221;</literal></emphasis></para>
          </listitem>
        </itemizedlist>		      
        
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>If 
                <emphasis>display-character</emphasis> is implemented on a platform, the
                property 
                <emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis> in the 
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node must be provided if greater than the
                required minimum default of 4 characters.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>If 
                <emphasis>display-character</emphasis> is implemented on a platform, the
                property 
                <emphasis role="bold"><literal>&#8220;ibm,display-number-of-lines&#8221;</literal></emphasis> in the
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node must be provided if greater than the
                required minimum default of 1 line.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>If the 
                <emphasis role="bold"><literal>&#8220;ibm,display-number-of-lines&#8221;</literal></emphasis> is greater
                than one, the platform must support form-feed (FF) (0x0C).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If form-feed is implemented, it must
                clear the display and position the display pointer to line 1 column
                1.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The platform must include the property 
                <emphasis role="bold"><literal>&#8220;ibm,form-feed&#8221;</literal></emphasis>
                in the
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_71785">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>For the 
                <emphasis>display-character</emphasis> RTAS call, when the truncation
                length as specified in the 
                <emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis> property,
                when it exists, is less than the length of the line being displayed on
                that particular line, then the firmware must truncate the requested line
                to be displayed to the length specified in the 
                <emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis> property
                for that line.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_57353">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para>For the 
                <emphasis>display-character</emphasis> RTAS call, when the truncation
                length as specified in the 
                <emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis> property,
                when it exists, is greater than the length specified of the line as
                specified in 
                <emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis> then the
                platform must provide a platform-dependent method of displaying the line
                to the user.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para>For platforms that use converged location
                codes, the platform must provide scrolling for the 
                <emphasis>display-character</emphasis> RTAS call, on the second line of
                the display, and must provide the 
                <emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis> property
                and specify a truncation length of no less than 80 characters for that
                line.</para>
                <para>
                <emphasis role="bold">Platform and Software Implementation Note:</emphasis> In
                implementing Requirements 
                <xref linkend="dbdoclet.50569332_71785" /> and 
                <xref linkend="dbdoclet.50569332_57353" />, it is permissible to have a
                separate buffer for any of the lines of the display and not display that
                line until a button is pressed.</para>
                <para>The RTAS call display-character can be used by the OS to display
                informative messages during boot, or to display error messages when an
                error has occurred and the OS cannot depend on its display drivers. This
                call is intended to display the alpha-numeric characters on an LCD panel,
                graphics console, or attached tty. The precise implementation is platform
                vendor specific.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>display-character</emphasis> call using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_26403" /> to place a character on the
                output device.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
              <listitem>
                <para>The OS must serialize all calls to 
                <emphasis>display-character</emphasis> with any other use of the 
                <emphasis>rtas-display-device</emphasis>.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26403">
                  <title>Argument Call Buffer
                  <emphasis>display-character</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>display-character</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>Value</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Character to be displayed</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: Device busy, try again later</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_41375">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
              <listitem>
                <para>If a physical
                output device is used for the output of the RTAS 
                <emphasis>display-character</emphasis> call, then it must have at least
                one line and 4 characters.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
              <listitem>
                <para>Certain ASCII control characters must
                have their normal meanings with respect to position on output devices
                which are capable of cursor positioning. In particular, ^M (0x0D) must
                position the cursor at column 0 in the current line, and ^J (0x0A) must
                move the cursor to the next line. If on the bottom line, move to column 0
                and scroll old data off the top.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
              <listitem>
                <para>The ASCII characters which must be
                displayed are generally those coded from 0x20 to 0x7E as shown in 
                <xref linkend="dbdoclet.50569332_48893" />. SP indicates a space and ND
                is not defined</para>
                
                <table frame="none" pgwide="1" xml:id="dbdoclet.50569332_48893">
                  <title>Display ASCII Characters</title>
                  <tgroup cols="12">
                    <colspec colname="c1" colwidth="8*" />
                    <colspec colname="c2" colwidth="8*" />
                    <colspec colname="c3" colwidth="8*" />
                    <colspec colname="c4" colwidth="8*" />
                    <colspec colname="c5" colwidth="8*" />
                    <colspec colname="c6" colwidth="8*" />
                    <colspec colname="c7" colwidth="8*" />
                    <colspec colname="c8" colwidth="8*" />
                    <colspec colname="c9" colwidth="8*" />
                    <colspec colname="c10" colwidth="8*" />
                    <colspec colname="c11" colwidth="8*" />
                    <colspec colname="c12" colwidth="8*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Hex</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Disp</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>SP</para>
                        </entry>
                        <entry>
                          <para>30</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>40</para>
                        </entry>
                        <entry>
                          <para>@</para>
                        </entry>
                        <entry>
                          <para>50</para>
                        </entry>
                        <entry>
                          <para>P</para>
                        </entry>
                        <entry>
                          <para>60</para>
                        </entry>
                        <entry>
                          <para>&#8216;</para>
                        </entry>
                        <entry>
                          <para>70</para>
                        </entry>
                        <entry>
                          <para>p</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>21</para>
                        </entry>
                        <entry>
                          <para>!</para>
                        </entry>
                        <entry>
                          <para>31</para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                        <entry>
                          <para>41</para>
                        </entry>
                        <entry>
                          <para>A</para>
                        </entry>
                        <entry>
                          <para>51</para>
                        </entry>
                        <entry>
                          <para>Q</para>
                        </entry>
                        <entry>
                          <para>61</para>
                        </entry>
                        <entry>
                          <para>a</para>
                        </entry>
                        <entry>
                          <para>71</para>
                        </entry>
                        <entry>
                          <para>q</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>22</para>
                        </entry>
                        <entry>
                          <para>&#8220;</para>
                        </entry>
                        <entry>
                          <para>32</para>
                        </entry>
                        <entry>
                          <para>2</para>
                        </entry>
                        <entry>
                          <para>42</para>
                        </entry>
                        <entry>
                          <para>B</para>
                        </entry>
                        <entry>
                          <para>52</para>
                        </entry>
                        <entry>
                          <para>R</para>
                        </entry>
                        <entry>
                          <para>62</para>
                        </entry>
                        <entry>
                          <para>b</para>
                        </entry>
                        <entry>
                          <para>72</para>
                        </entry>
                        <entry>
                          <para>r</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>23</para>
                        </entry>
                        <entry>
                          <para>#</para>
                        </entry>
                        <entry>
                          <para>33</para>
                        </entry>
                        <entry>
                          <para>3</para>
                        </entry>
                        <entry>
                          <para>43</para>
                        </entry>
                        <entry>
                          <para>C</para>
                        </entry>
                        <entry>
                          <para>53</para>
                        </entry>
                        <entry>
                          <para>S</para>
                        </entry>
                        <entry>
                          <para>63</para>
                        </entry>
                        <entry>
                          <para>c</para>
                        </entry>
                        <entry>
                          <para>73</para>
                        </entry>
                        <entry>
                          <para>s</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>24</para>
                        </entry>
                        <entry>
                          <para>$</para>
                        </entry>
                        <entry>
                          <para>34</para>
                        </entry>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>44</para>
                        </entry>
                        <entry>
                          <para>D</para>
                        </entry>
                        <entry>
                          <para>54</para>
                        </entry>
                        <entry>
                          <para>T</para>
                        </entry>
                        <entry>
                          <para>64</para>
                        </entry>
                        <entry>
                          <para>d</para>
                        </entry>
                        <entry>
                          <para>74</para>
                        </entry>
                        <entry>
                          <para>t</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>25</para>
                        </entry>
                        <entry>
                          <para>%</para>
                        </entry>
                        <entry>
                          <para>35</para>
                        </entry>
                        <entry>
                          <para>5</para>
                        </entry>
                        <entry>
                          <para>45</para>
                        </entry>
                        <entry>
                          <para>E</para>
                        </entry>
                        <entry>
                          <para>55</para>
                        </entry>
                        <entry>
                          <para>U</para>
                        </entry>
                        <entry>
                          <para>65</para>
                        </entry>
                        <entry>
                          <para>e</para>
                        </entry>
                        <entry>
                          <para>75</para>
                        </entry>
                        <entry>
                          <para>u</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>26</para>
                        </entry>
                        <entry>
                          <para>&amp;</para>
                        </entry>
                        <entry>
                          <para>36</para>
                        </entry>
                        <entry>
                          <para>6</para>
                        </entry>
                        <entry>
                          <para>46</para>
                        </entry>
                        <entry>
                          <para>F</para>
                        </entry>
                        <entry>
                          <para>56</para>
                        </entry>
                        <entry>
                          <para>V</para>
                        </entry>
                        <entry>
                          <para>66</para>
                        </entry>
                        <entry>
                          <para>f</para>
                        </entry>
                        <entry>
                          <para>76</para>
                        </entry>
                        <entry>
                          <para>v</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>27</para>
                        </entry>
                        <entry>
                          <para>&#8216;</para>
                        </entry>
                        <entry>
                          <para>37</para>
                        </entry>
                        <entry>
                          <para>7</para>
                        </entry>
                        <entry>
                          <para>47</para>
                        </entry>
                        <entry>
                          <para>G</para>
                        </entry>
                        <entry>
                          <para>57</para>
                        </entry>
                        <entry>
                          <para>W</para>
                        </entry>
                        <entry>
                          <para>67</para>
                        </entry>
                        <entry>
                          <para>g</para>
                        </entry>
                        <entry>
                          <para>77</para>
                        </entry>
                        <entry>
                          <para>w</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>28</para>
                        </entry>
                        <entry>
                          <para>(</para>
                        </entry>
                        <entry>
                          <para>38</para>
                        </entry>
                        <entry>
                          <para>8</para>
                        </entry>
                        <entry>
                          <para>48</para>
                        </entry>
                        <entry>
                          <para>H</para>
                        </entry>
                        <entry>
                          <para>58</para>
                        </entry>
                        <entry>
                          <para>X</para>
                        </entry>
                        <entry>
                          <para>68</para>
                        </entry>
                        <entry>
                          <para>h</para>
                        </entry>
                        <entry>
                          <para>78</para>
                        </entry>
                        <entry>
                          <para>x</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>29</para>
                        </entry>
                        <entry>
                          <para>)</para>
                        </entry>
                        <entry>
                          <para>39</para>
                        </entry>
                        <entry>
                          <para>9</para>
                        </entry>
                        <entry>
                          <para>49</para>
                        </entry>
                        <entry>
                          <para>I</para>
                        </entry>
                        <entry>
                          <para>59</para>
                        </entry>
                        <entry>
                          <para>Y</para>
                        </entry>
                        <entry>
                          <para>69</para>
                        </entry>
                        <entry>
                          <para>i</para>
                        </entry>
                        <entry>
                          <para>79</para>
                        </entry>
                        <entry>
                          <para>y</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2A</para>
                        </entry>
                        <entry>
                          <para>*</para>
                        </entry>
                        <entry>
                          <para>3A</para>
                        </entry>
                        <entry>
                          <para>:</para>
                        </entry>
                        <entry>
                          <para>4A</para>
                        </entry>
                        <entry>
                          <para>J</para>
                        </entry>
                        <entry>
                          <para>5A</para>
                        </entry>
                        <entry>
                          <para>Z</para>
                        </entry>
                        <entry>
                          <para>6A</para>
                        </entry>
                        <entry>
                          <para>j</para>
                        </entry>
                        <entry>
                          <para>7A</para>
                        </entry>
                        <entry>
                          <para>z</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2B</para>
                        </entry>
                        <entry>
                          <para>+</para>
                        </entry>
                        <entry>
                          <para>3B</para>
                        </entry>
                        <entry>
                          <para>;</para>
                        </entry>
                        <entry>
                          <para>4B</para>
                        </entry>
                        <entry>
                          <para>K</para>
                        </entry>
                        <entry>
                          <para>5B</para>
                        </entry>
                        <entry>
                          <para>[</para>
                        </entry>
                        <entry>
                          <para>6B</para>
                        </entry>
                        <entry>
                          <para>k</para>
                        </entry>
                        <entry>
                          <para>7B</para>
                        </entry>
                        <entry>
                          <para>{</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2C</para>
                        </entry>
                        <entry>
                          <para>,</para>
                        </entry>
                        <entry>
                          <para>3C</para>
                        </entry>
                        <entry>
                          <para>&lt;</para>
                        </entry>
                        <entry>
                          <para>4C</para>
                        </entry>
                        <entry>
                          <para>L</para>
                        </entry>
                        <entry>
                          <para>5C</para>
                        </entry>
                        <entry>
                          <para>\</para>
                        </entry>
                        <entry>
                          <para>6C</para>
                        </entry>
                        <entry>
                          <para>l</para>
                        </entry>
                        <entry>
                          <para>7C</para>
                        </entry>
                        <entry>
                          <para>|</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2D</para>
                        </entry>
                        <entry>
                          <para>-</para>
                        </entry>
                        <entry>
                          <para>3D</para>
                        </entry>
                        <entry>
                          <para>=</para>
                        </entry>
                        <entry>
                          <para>4D</para>
                        </entry>
                        <entry>
                          <para>M</para>
                        </entry>
                        <entry>
                          <para>5D</para>
                        </entry>
                        <entry>
                          <para>]</para>
                        </entry>
                        <entry>
                          <para>6D</para>
                        </entry>
                        <entry>
                          <para>m</para>
                        </entry>
                        <entry>
                          <para>7D</para>
                        </entry>
                        <entry>
                          <para>}</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2E</para>
                        </entry>
                        <entry>
                          <para>.</para>
                        </entry>
                        <entry>
                          <para>3E</para>
                        </entry>
                        <entry>
                          <para>&gt;</para>
                        </entry>
                        <entry>
                          <para>4E</para>
                        </entry>
                        <entry>
                          <para>N</para>
                        </entry>
                        <entry>
                          <para>5E</para>
                        </entry>
                        <entry>
                          <para>^</para>
                        </entry>
                        <entry>
                          <para>6E</para>
                        </entry>
                        <entry>
                          <para>n</para>
                        </entry>
                        <entry>
                          <para>7E</para>
                        </entry>
                        <entry>
                          <para>~</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2F</para>
                        </entry>
                        <entry>
                          <para>/</para>
                        </entry>
                        <entry>
                          <para>3F</para>
                        </entry>
                        <entry>
                          <para>?</para>
                        </entry>
                        <entry>
                          <para>4F</para>
                        </entry>
                        <entry>
                          <para>O</para>
                        </entry>
                        <entry>
                          <para>5F</para>
                        </entry>
                        <entry>
                          <para>_</para>
                        </entry>
                        <entry>
                          <para>6F</para>
                        </entry>
                        <entry>
                          <para>o</para>
                        </entry>
                        <entry>
                          <para>7F</para>
                        </entry>
                        <entry>
                          <para>ND</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>Software Implementation Note: Care should be taken in using the
                full character set for all systems as some characters may not be
                available or may display in a different fashion. For instance, the
                currency symbol, $ (0x24), may be modified to a national currency symbol.
                Other currently known differences occur for the reverse slant, \ (0x5C),
                and the tilde, ~(0x7E).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_54841">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10053" 
            xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
              <listitem>
                <para>RTAS must not
                output characters to the 
                <emphasis>rtas-display-device</emphasis> except for explicit calls from
                the OS to the 
                <emphasis>display-character</emphasis> function except for the following
                conditions.</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The <emphasis>rtas-display-device</emphasis> is marked 
                    <emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>.</para>
                  </listitem>
          
                  <listitem>
                    <para>The RTAS call is 
                    <emphasis>power-off, ibm,power-off-ups, set-power-level
                    (0,0),</emphasis> or
                    <emphasis>system-reboot</emphasis>.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
        </variablelist>
  
        
        <para>
          <emphasis role="bold">Software Implementation Notes:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>RTAS should try to produce output to the user. This could be to
            the system console, to an attached terminal, or to some other device. It
            could be implemented using a diagnostic processor or network. RTAS could
            also implement this call by storing the messages in a buffer in NVRAM so
            the user could determine the reason for a crash upon reboot.</para>
          </listitem>
  
          <listitem>
            <para>This call modifies the registers associated with the 
            <emphasis>rtas-display-device</emphasis>. The OS may also access this
            device, being aware that calls to 
            <emphasis>display-character</emphasis> change the state of the
            device.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="dbdoclet.50569332_32164">
        <title><emphasis>set-indicator</emphasis></title>
        <para>The RTAS 
        <emphasis>set-indicator</emphasis> function provides the OS with an
        abstraction for controlling various lights, indicators, and other
        resources on a platform. If multiple indicators of a given type are
        provided by the platform, this function permits addressing them
        individually.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_32164" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>set-indicator</emphasis> call which sets the value of the
                indicator of type 
                <emphasis>Indicator</emphasis> and index 
                <emphasis>Indicator-index</emphasis> using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_27587" /> and indicator types defined by 
                <xref linkend="dbdoclet.50569332_32237" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_27587">
                  <title>Argument Call Buffer
                  <emphasis>set-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">Name</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Values</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="5">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>set-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 type of indicator</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Indicator-index</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Index of specific indicator (0, 1,...)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>State</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Desired new state</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>990x: Extended Delay</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Hardware busy, try again later</para>
                          <para>-3: No such indicator implemented</para>
                          <para>-9000: Multi-level isolation error</para>
                          <para>-9001: Valid outstanding translation</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_32164" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>For indicators in the 
                <emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> property, the indices
                for indicators must start at zero (0) and increment sequentially up to
                the maximum index; that is, all of the integers and only those integers
                from 0 to the maximum index are valid.</para>
                <para>
                <emphasis role="bold">Architecture Note:</emphasis> Indicator indices that are
                obtained via the 
                <emphasis>ibm,get-indices</emphasis> RTAS call are not necessarily
                contiguous (that is, any of the indices between 0 and the 
                <emphasis>maxindex</emphasis>, inclusive, may be missing).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_32164" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>Of the indicator types defined by 
                <xref linkend="dbdoclet.50569332_32237" />, RTAS must implement at least
                Tone Frequency and Tone Volume.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_32164" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>set-indicator</emphasis> RTAS call must not return a busy
                indication (-2 or 990x) for any indicator in 
                <xref linkend="dbdoclet.50569332_32237" /> which is marked with a
                &#8220;yes&#8221; in the &#8220;Fast?&#8221; column of that table.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_32164" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The platform may, but is not required to,
                turn off a tone automatically after 5 minutes or more duration (that is,
                automatically set the Tone Volume to zero), and therefore a user of the
                Tone must call 
                <emphasis>set-indicator</emphasis> Tone Volume with a volume value of
                non-zero, if a tone is to be sustained longer than 5 minutes, and if the
                platform is going to automatically terminate the tone, the platform must
                reset its automatic turn-off timer when it receives a 
                <emphasis>set-indicator</emphasis> call for the Tone Volume with a
                non-zero tone volume value.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
        
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_32237">
          <title>Defined Indicators</title>
          <tgroup cols="8">
            <colspec colname="c1" colwidth="12*" />
            <colspec colname="c2" colwidth="12*" />
            <colspec colname="c3" colwidth="12*" />
            <colspec colname="c4" colwidth="12*" />
            <colspec colname="c5" colwidth="12*" />
            <colspec colname="c6" colwidth="12*" />
            <colspec colname="c7" colwidth="12*" />
            <colspec colname="c8" colwidth="12*" />
            <thead>
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Indicator Name</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Token Value</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Defined Values</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Default Value</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Fast?</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Required?</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">&lt;vendor&gt;
                    <footnote xml:id="pgfId-1272284">
                      <para>Values in the &#8220;&lt;vendor&gt;&#8221; column are
                      used to replace the &#8220;
                      <emphasis>&lt;vendor&gt;</emphasis>&#8221; field of the 
                      <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>
                      property, when that property is
                      presented. See Requirement 
                      <xref linkend="dbdoclet.50569332_74895" />.</para>
                    </footnote></emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Examples/Comments</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <para>Tone Frequency</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Unsigned Integer</para>
                  <para>(units are Hz)</para>
                </entry>
                <entry>
                  <para>1000</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>When tone is required. See Requirement 
                  <xref linkend="LoPAR.Platform" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Generate an audible tone using the tone generator
                  hardware. RTAS selects the closest implemented audible
                  frequency to the requested value.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Tone Volume</para>
                </entry>
                <entry>
                  <para>2</para>
                </entry>
                <entry>
                  <para>0-100 (units are percent),</para>
                  <para>0 = OFF</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>When tone is required. See Requirement 
                  <xref linkend="LoPAR.Platform" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Set the percentage of full volume of the tone generator
                  output, scaled approximately logarithmically. RTAS should
                  select the closest implemented volume for values between zero
                  (off) and 100 (full on).</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>3-6</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>7</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Battery Warning Time.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Condition Cycle
                  Request.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Surveillance</para>
                </entry>
                <entry>
                  <para>9000</para>
                </entry>
                <entry>
                  <para>0-disabled</para>
                  <para>1-255-timeout</para>
                </entry>
                <entry>
                  <para>sp-sti</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>When the platform implements the surveillance
                  function.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Initialized with value from the sp-sti system
                  parameter.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Isolation-state</para>
                </entry>
                <entry>
                  <para>9001</para>
                </entry>
                <entry>
                  <para>Isolate = 0</para>
                  <para>Unisolate = 1</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>For all DR options</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Isolate refers to the DR action to logically disconnect
                  from the platform and/or OS (for example, for PCI, isolate from
                  the bus and from the OS). See 
                  <xref linkend="LoPAR.Virtualization" /> for more
                  details.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>DR</para>
                </entry>
                <entry>
                  <para>9002</para>
                </entry>
                <entry>
                  <para>Inactive = 0</para>
                  <para>Active = 1</para>
                  <para>Identify = 2</para>
                  <para>Action = 3</para>
                </entry>
                <entry>
                  <para>0 if Inactive</para>
                  <para>1 if Active</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>For all DR options</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Indicator index may refer to a single indicator that
                  combines Power/Active indicator and Identify/Action indications
                  or just an Identify/Action indicator. Identify and Action may
                  map to the same visual state (for example, the same blink
                  rate). See 
                  <xref linkend="LoPAR.Error" /> and 
                  <xref linkend="LoPAR.Virtualization" /> for more
                  information.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Allocation-state</para>
                </entry>
                <entry>
                  <para>9003</para>
                </entry>
                <entry>
                  <para>unusable (0)</para>
                  <para>usable (1)</para>
                  <para>exchange (2)</para>
                  <para>recover (3)</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>For all DR options</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Allows an OS image to assign (usable, exchange, or
                  recover) resources from the firmware or, release resources from
                  the OS to the firmware. See 
                  <xref linkend="LoPAR.Virtualization" /> for more
                  details.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>9004</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Global Interrupt Queue Control</para>
                </entry>
                <entry>
                  <para>9005</para>
                </entry>
                <entry>
                  <para>Disable = 0</para>
                  <para>Enable = 1</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>See Requirement 
                  <xref linkend="dbdoclet.50569332_26651" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Enable and Disable the processor as Global Interrupt
                  Queue Server</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Error Log</para>
                  <para>or</para>
                  <para>FRU Fault</para>
                </entry>
                <entry>
                  <para>9006</para>
                </entry>
                <entry>
                  <para>Normal (off) = 0</para>
                  <para>Fault (on) = 1</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>Yes</para>
                  <para>See 
                  <xref linkend="LoPAR.Error" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>This indicator is combined with the Identify indicator
                  for the Primary Enclosure drawer/enclosure (that is, is the
                  same physical indicator). Off indicates that the system is
                  working normally. On indicates that the system hardware,
                  firmware and/or diagnostics detected a fault (failure) in the
                  system or a partition requires operator intervention for
                  another reason. The Error Log indicator is located only on the
                  Primary Enclosure. See 
                  <xref linkend="LoPAR.Error" /> and 
                  <xref linkend="LoPAR.Virtualization" /> for more
                  information.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Identify (Locate)</para>
                </entry>
                <entry>
                  <para>9007</para>
                </entry>
                <entry>
                  <para>Normal (off) = 0</para>
                  <para>Identify (blink) = 1</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>Yes</para>
                  <para>See 
                  <xref linkend="LoPAR.Error" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Note that a 9002 indicator also has an Identify state,
                  and in the case where the 9002 indicator is implemented with
                  two physical indicators (one for Power and one for
                  Identify/Action), the same physical indicator must be used for
                  both a 9002 Identify/Action indicator and 9007 Identify
                  indicator. This architecture does not specify any mechanism for
                  protecting against the simultaneous use by the user of an
                  indicator that is both a 9002 and 9007 indicator, nor does it
                  protect against the use of multiple 9007 indicators
                  simultaneously or multiple uses of the same 9007 indicator
                  simultaneously. See 
                  <xref linkend="LoPAR.Error" /> and 
                  <xref linkend="LoPAR.Virtualization" /> for more
                  information.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>9008</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>9009</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Vendor Specific</para>
                </entry>
                <entry>
                  <para>9100-9999</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&lt;vendor&gt;
                  <footnote xml:id="pgfId-1272636">
                    <para>The vendor specific company representation, as used on
                    other OF properties specified by that vendor.</para>
                  </footnote></para>
                </entry>
                <entry>
                  <para>Indicator values reserved for platform vendor use.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      
        <section>
          <title>Indicators</title>
          <para />
        
          <section xml:id="sec_indicator_9000_surveilance">
            <title>Indicator 9000 Surveillance</title>
            <para>An indicator is defined with the token value 9000 to allow
            temporary modification of the state of the surveillance function (further
            described in 
            <xref linkend="dbdoclet.50569332_60143" />).</para>
            <para>To enable monitoring of heartbeats from the 
            <emphasis>event-scan</emphasis> RTAS call, the surveillance indicator is
            set with a value of 1 to 255, indicating the number of minutes for the
            surveillance time-out value. If monitoring is already enabled, the
            time-out value can be modified by setting this indicator. To disable
            monitoring, the surveillance indicator should be set to a value of zero
            (0). The 
            <emphasis>set-indicator</emphasis> call is used to modify the state of
            surveillance (overriding the default system parameter values) only for
            the current session. The surveillance state returns to the default values
            when the system is rebooted.</para>
            <para>The default surveillance configuration may be modified by changing
            the system parameters. For more information on these parameters, refer to
            
            <xref linkend="dbdoclet.50569332_60143" />.</para>
      
            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_indicator_9000_surveilance" 
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>Platforms with the surveillance
                    function must implement a sensor and an indicator, with the token value
                    of 9000, with defined state input values of on (= 1-255, which enables
                    surveillance with specified time-out value in minutes) and off (= 0,
                    which disables surveillance).</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
      
            <para>
            <emphasis role="bold">Firmware Implementation Note:</emphasis> The requirement above
            results in the creation of the properties 
            <emphasis role="bold"><literal>&#8220;ibm,indicator-9000&#8221;</literal></emphasis> and 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9000&#8221;</literal></emphasis> in the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
            <para>
            <emphasis role="bold">Hardware Implementation Note:</emphasis> The action that the
            service processor takes in the case of a timeout is determined by the
            configuration setup policy in the system parameters.</para>
          </section>
          
          <section xml:id="sec_indicator_9005_giqc">
            <title>Indicator 9005 Global Interrupt Queue Control</title>
            <para>The 9005 indicator controls the global interrupt server queue logic
            of the interrupt presentation controllers for the processor making the
            call (Available Processor Mask (APM) for the PowerPC interrupt
            presentation controller). This is used when bringing a processor online
            and taking a processor offline.</para>
      
            <variablelist>
             	<varlistentry xml:id="dbdoclet.50569332_26651">
                <term><emphasis role="bold">R1-<xref linkend="sec_indicator_9005_giqc" 
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>Platforms that
                    allow processors to be brought online or be taken offline dynamically
                    must implement the global interrupt queue control indicator with a value
                    of 9005 as specified in 
                    <xref linkend="dbdoclet.50569332_32237" />.</para>
                  </listitem>
             	</varlistentry>
             	
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_indicator_9005_giqc" 
                xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                  <listitem>
                    <para>The index value for global interrupt
                    queue control indicator (9005) must be</para>
                    <para>(2
                    <emphasis>ibm,interruptserver#-size</emphasis>) - 1 - the 
                    <emphasis role="bold"><literal>gserver#</literal></emphasis> of the global server to be controlled as
                    given in the
                    <emphasis role="bold"><literal>
                    &#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis> property.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
      
          </section>

        </section>

      </section>
      
      <section xml:id="dbdoclet.50569332_10754">
        <title><emphasis>get-sensor-state</emphasis></title>
        <para>The RTAS call 
        <emphasis>get-sensor-state</emphasis> is used by the OS to read the
        current state of various sensors on any Platform. If multiple sensors of
        a given type are provided by the platform, this function permits
        addressing them individually.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10754" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>get-sensor-state</emphasis> call which
                reads the value of the sensor of type 
                <emphasis>Sensor</emphasis> which has index 
                <emphasis>Sensor-index</emphasis> using the argument call buffer defined
                by 
                <xref linkend="dbdoclet.50569332_20789" /> and the sensor types defined by
                
                <xref linkend="dbdoclet.50569332_23534" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10754" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>If a platform tests sensor values against
                limits, then RTAS must return the result of these tests using the 
                <emphasis>Status</emphasis> output parameter.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20789.1">
                  <title><emphasis>get-sensor-state</emphasis> Argument Call Buffer</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for get-sensor-state</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Sensor</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token defining the sensor type</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Sensor-index</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Index of specific sensor (0, 1,...)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <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
                          below)</para>
                          <para>13: Sensor value &gt;= Critical high</para>
                          <para>12: Sensor value &gt;= Warning high</para>
                          <para>11: Sensor value normal</para>
                          <para>10: Sensor value &lt;= Warning low</para>
                          <para>9: Sensor value &lt;= Critical low</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Hardware Busy, Try again later</para>
                          <para>-3: No such sensor implemented</para>
                          <para>-9000: DR Entity isolated (
                          <xref linkend="LoPAR.Virtualization" />)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>State</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Current value as defined in the Defined Values column of 
                          <xref linkend="dbdoclet.50569332_23534" />.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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>get-sensor-state</emphasis> again. However, software may issue
                the 
                <emphasis>get-sensor-state</emphasis> call again either earlier or later
                than this.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10754" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>For sensors in the 
                <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property, the indices for
                sensors must start at zero (0) and increment sequentially up to the
                maximum index; that is, all of the integers and only those integers from
                0 to the maximum index are valid.</para>
                <para>
                <emphasis role="bold">Architecture Note:</emphasis> Sensor indices that are obtained
                via the 
                <emphasis>ibm,get-indices</emphasis> RTAS call are not necessarily
                contiguous (that is, any of the indices between 0 and the 
                <emphasis>maxindex</emphasis>, inclusive, may be missing).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_10754" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>get-sensor</emphasis> RTAS call must not return a busy
                indication (-2 or 990x) for any indicator in 
                <xref linkend="dbdoclet.50569332_23534" /> which is marked with a
                &#8220;yes&#8221; in the &#8220;Fast?&#8221; column of that table.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Hardware Implementation Note:</emphasis> Some platforms may
        compare the value of environmental sensors (such as the Battery Voltage
        or Thermal Sensor) to some limits. When the value of the sensor meets or
        exceeds a limit, the platform may take some action. RTAS makes the OS
        aware of the relationship of the sensor values to the limit by using the 
        <emphasis>Status</emphasis> code to return this information.</para>
        <para>
        <emphasis role="bold">Software and Hardware Implementation Notes:</emphasis> The
        meaning of these limits is as follows:</para>
  
        <itemizedlist>		      
          <listitem>
            <para>Critical High - The sensor value is greater than or equal to this
            limit. The platform may take some action and may initiate an EPOW (see 
            <xref linkend="LoPAR.Error" />). The OS may take some action
            to correct this situation or to perform an orderly shutdown.</para>
          </listitem>
          
          <listitem>
            <para>Warning High - The sensor value is greater than or equal to this
            limit, but less than the critical high limit. The platform may initiate a
            warning EPOW. The OS may take some action to bring this reading back into
            the normal range.</para>
          </listitem>
          
          <listitem>
            <para>Normal - RTAS is aware of the limits and the value is within
            these operating limits.</para>
          </listitem>
          
          <listitem>
            <para>Warning Low - The sensor value is less than or equal to this
            limit, but greater than the critical low limit. The platform may initiate
            a warning EPOW. The OS may take some action to bring this reading back
            into the normal range.</para>
          </listitem>
          
          <listitem>
            <para>Critical Low - The sensor value is less than or equal to this
            limit. The platform may take some action and may initiate an EPOW. The OS
            may take some action to correct this situation or to perform an orderly
            shutdown.</para>
            
            <para>Where:</para>
          </listitem>
          
          <listitem>
            <para>A &#8216;critical&#8217; state is defined as a condition where
            the sensor value of the measured item indicates that it is outside the
            allowable operating parameters of the system, and that a failure is
            imminent unless some immediate action is taken.</para>
          </listitem>
          
          <listitem>
            <para>A &#8216;warning&#8217; state is defined as a condition where the
            sensor value of the measured item indicates that it is outside the
            expected operating parameters for normal operation, but has not yet
            reached a critical state. The variance is significant enough that either
            system software or an operator may want to take some action to bring the
            parameter back into the normal range.</para>
          </listitem>
        </itemizedlist>		      
        
        <para>
        <emphasis role="bold">Platform Implementation Note:</emphasis> The existence of this
        sensor state reporting capability should not be construed as a
        requirement to have any limits on sensors or to always have all four
        limits.</para>
        
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_23534">
          <title>Defined Sensors</title>
          <tgroup cols="7">
            <colspec colname="c1" colwidth="14*" />
            <colspec colname="c2" colwidth="14*" />
            <colspec colname="c3" colwidth="14*" />
            <colspec colname="c4" colwidth="14*" />
            <colspec colname="c5" colwidth="14*" />
            <colspec colname="c6" colwidth="14*" />
            <colspec colname="c7" colwidth="14*" />
            <thead>
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Sensor Name</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Token Value</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Defined Values</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Fast?</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Required?</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">&lt;vendor&gt;
                    <footnote xml:id="pgfId-1271585">
                      <para>Values in the &#8220;&lt;vendor&gt;&#8221; column are
                      used to replace the &#8220;
                      <emphasis>&lt;vendor&gt;</emphasis>&#8221; field of 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, when that property is presented. See Requirement 
                      <xref linkend="dbdoclet.50569332_29762" />.</para>
                    </footnote></emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Description</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <para>Key Switch</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Off (0),</para>
                  <para>Normal (1),</para>
                  <para>Secure (2),</para>
                  <para>Maintenance (3)</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>No</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Key switch modes are tied to OS security policy.
                  Suggested meanings: Maintenance mode permits booting from
                  floppy or other external, non-secure media. Normal mode permits
                  boot from any attached device. Secure mode permits no manual
                  choice of boot device, and may restrict available functionality
                  which is accessed from the main operator station. Off
                  completely disables the system.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>2</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Thermal</para>
                </entry>
                <entry>
                  <para>3</para>
                </entry>
                <entry>
                  <para>Temperature</para>
                  <para>(in Degrees Celsius)</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>No</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>If implemented, returns the internal temperature of the
                  specified thermal sensor.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Lid Status.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>5</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>6</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Current battery output
                  voltage.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>7</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Battery Capacity
                  Remaining.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Battery Capacity
                  Percentage.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Environmental and</para>
                  <para>Power State (EPOW)</para>
                </entry>
                <entry>
                  <para>9</para>
                </entry>
                <entry>
                  <para>EPOW_Reset(0)</para>
                  <para>Warn_Cooling(1)</para>
                  <para>Warn_Power(2)</para>
                  <para>System_Shutdown(3)</para>
                  <para>System_Halt(4)</para>
                  <para>EPOW_Main_Enclosure(5)</para>
                  <para>EPOW_Power_Off(7)</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>Yes</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>RTAS assessment of the environment and power state of the
                  platform.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>10</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Battery Condition Cycle
                  State.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>11</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Reserved. Was (deprecated) Battery Charging State.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Surveillance</para>
                </entry>
                <entry>
                  <para>9000</para>
                </entry>
                <entry>
                  <para>1-255 and 0</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>When the platform implements the surveillance
                  function</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Current state of surveillance.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Fan speed</para>
                </entry>
                <entry>
                  <para>9001</para>
                </entry>
                <entry>
                  <para>fan - rpm</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>No</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Voltage</para>
                </entry>
                <entry>
                  <para>9002</para>
                </entry>
                <entry>
                  <para>voltage - mv</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>No</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>DR-entity-sense</para>
                </entry>
                <entry>
                  <para>9003</para>
                </entry>
                <entry>
                  <para>DR connector empty = 0</para>
                  <para>DR entity present = 1</para>
                  <para>DR entity unusable (2)</para>
                  <para>DR entity available for exchange (3)</para>
                  <para>DR entity available for recovery (4)</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>For all DR options</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>Used in Dynamic Reconfiguration operations to determine
                  if connector is available and whether the user performed a
                  particular DR operation correctly. See 
                  <xref linkend="LoPAR.Virtualization" /> and 
                  <xref linkend="LoPAR.Virtualization" />.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Power Supply</para>
                </entry>
                <entry>
                  <para>9004</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>No</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Sense presence and status of power supplies.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Global Interrupt Queue Control</para>
                </entry>
                <entry>
                  <para>9005</para>
                </entry>
                <entry>
                  <para>Disabled = 0</para>
                  <para>Enabled = 1</para>
                </entry>
                <entry>
                  <para>yes</para>
                </entry>
                <entry>
                  <para>See Requirement 
                  <xref linkend="dbdoclet.50569332_26651" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Global interrupt queue server control state.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Error Log</para>
                  <para>or</para>
                  <para>FRU Fault</para>
                </entry>
                <entry>
                  <para>9006</para>
                </entry>
                <entry>
                  <para>Normal (off) = 0</para>
                  <para>Fault (on) = 1</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>Yes</para>
                  <para>See 
                  <xref linkend="LoPAR.Error" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Off indicates that the system is working normally.</para>
                  <para>On indicates that the system hardware, firmware and/or
                  diagnostics detected a fault in the system.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Identify</para>
                </entry>
                <entry>
                  <para>9007</para>
                </entry>
                <entry>
                  <para>Normal (off) = 0</para>
                  <para>Identify (blink) = 1</para>
                </entry>
                <entry>
                  <para>no</para>
                </entry>
                <entry>
                  <para>Yes</para>
                  <para>See 
                  <xref linkend="LoPAR.Error" />.</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Identify (locate) indicator (FRU, connector, or
                  drawer/unit).</para>
                  <para>Off is the default State.</para>
                  <para>On indicates the Identify State.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>9008</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>9009</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>-</para>
                </entry>
                <entry>
                  <para>ibm</para>
                </entry>
                <entry>
                  <para>Reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Vendor Specific</para>
                </entry>
                <entry>
                  <para>9100-9999</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&#160;</para>
                </entry>
                <entry>
                  <para>&lt;vendor&gt;
                  <footnote xml:id="pgfId-1271942">
                    <para>The vendor specific company representation, as used on
                    other OF properties specified by that vendor.</para>
                  </footnote></para>
                </entry>
                <entry>
                  <para>Reserved for use by platform vendors.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
        <section xml:id="sec_get_sensor_state">
          <title>Sensors</title>
          <para>The current state of surveillance, as described in 
          <xref linkend="dbdoclet.50569332_60143" />, is queried with a call to 
          <emphasis>get-sensor-state</emphasis> with a token value of 9000. Fan
          speed is queried with the token value of 9001 and an index specifying the
          desired fan. Similarly, voltage is sensed with a token value of 9002 and
          an index specifying the desired voltage source.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_get_sensor_state" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para>Platforms which implement the
                  surveillance function must implement a single defined RTAS sensor with
                  the token value of 9000, which returns values of on (= 1-255 minutes) and
                  off (= 0) to show the current state of surveillance during this
                  session.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_get_sensor_state" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para>Platforms with software visible fan
                  speed sensors must implement them as defined RTAS sensors with the token
                  value of 9001, which returns a sensor value in revolutions per minute
                  (RPM).</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_get_sensor_state" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para>Platforms with software visible voltage
                  sensors must implement them as defined RTAS sensors with the token value
                  of 9002, which returns a sensor value in millivolts.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para><emphasis role="bold">Hardware Implementation Note:</emphasis> 
          The notion of a delay, due to the
          sensor data acquisition time, may make it desirable to cache sensor data
          to avoid interlocking with the service processor.</para>
          <para><emphasis role="bold">Software Implementation Note:</emphasis>
          Software should not assume that
          sensor data returned is a real time reading.</para>
        
          <section>
            <title>Example Implementation of Sensors</title>
            <para>An example implementation of a platform with a service processor
            and four fans and four voltage sensors is represented by the paired
            integers (
            <emphasis>token maxindex</emphasis>) in the OF device tree as shown in 
            <xref linkend="dbdoclet.50569332_40884" />.</para>
            
            <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_40884">
              <title>Example - Contents of
              <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property</title>
              <tgroup cols="2">
                <colspec colname="c1" colwidth="50*" />
                <colspec colname="c2" colwidth="50*" />
                <thead>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">token</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">maxindex</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">(Any sensors withStandardSensor
                        Tokens)...</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">(Associated maxindex
                        values)...</emphasis>
                      </para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>9000 (surveillance)</para>
                    </entry>
                    <entry>
                      <para>0000</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>9001 (fan-speed)</para>
                    </entry>
                    <entry>
                      <para>0003</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>9002 (voltage)</para>
                    </entry>
                    <entry>
                      <para>0003</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>This requires sensors such as those shown in 
            <xref linkend="dbdoclet.50569332_17894" />.</para>
            
            <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_17894">
              <title>Example - Sensor Definitions</title>
              <tgroup cols="4">
                <colspec colname="c1" colwidth="25*" />
                <colspec colname="c2" colwidth="25*" />
                <colspec colname="c3" colwidth="25*" />
                <colspec colname="c4" colwidth="25*" />
                <thead>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">sensor</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">token</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">index</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">value</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>
                      <para>surveillance</para>
                    </entry>
                    <entry>
                      <para>9000</para>
                    </entry>
                    <entry>
                      <para>0000</para>
                    </entry>
                    <entry>
                      <para>0 / 1-255</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>fan#1 fan speed</para>
                    </entry>
                    <entry>
                      <para>9001</para>
                    </entry>
                    <entry>
                      <para>0000</para>
                    </entry>
                    <entry>
                      <para>fan rpm</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>fan#2 fan speed</para>
                    </entry>
                    <entry>
                      <para>9001</para>
                    </entry>
                    <entry>
                      <para>0001</para>
                    </entry>
                    <entry>
                      <para>fan rpm</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>fan#3 fan speed</para>
                    </entry>
                    <entry>
                      <para>9001</para>
                    </entry>
                    <entry>
                      <para>0002</para>
                    </entry>
                    <entry>
                      <para>fan rpm</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>fan#4 fan speed</para>
                    </entry>
                    <entry>
                      <para>9001</para>
                    </entry>
                    <entry>
                      <para>0003</para>
                    </entry>
                    <entry>
                      <para>fan rpm</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>voltage-level #1</para>
                    </entry>
                    <entry>
                      <para>9002</para>
                    </entry>
                    <entry>
                      <para>0000</para>
                    </entry>
                    <entry>
                      <para>voltage - mv</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>voltage-level #2</para>
                    </entry>
                    <entry>
                      <para>9002</para>
                    </entry>
                    <entry>
                      <para>0001</para>
                    </entry>
                    <entry>
                      <para>voltage - mv</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>voltage-level #3</para>
                    </entry>
                    <entry>
                      <para>9002</para>
                    </entry>
                    <entry>
                      <para>0002</para>
                    </entry>
                    <entry>
                      <para>voltage - mv</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>voltage-level #4</para>
                    </entry>
                    <entry>
                      <para>9002</para>
                    </entry>
                    <entry>
                      <para>0003</para>
                    </entry>
                    <entry>
                      <para>voltage - mv</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>In addition, the properties
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9000&#8221;</literal></emphasis>, 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9001&#8221;</literal></emphasis> and 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9002&#8221;</literal></emphasis> in the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node that each contain an array of strings.
            Each entry in the array contains the location code for the matching
            sensor. For example, the first entry of 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9001&#8221;</literal></emphasis> contains the location
            code for fan#1. Location codes are shown in 
            <xref linkend="LoPAR.Platform" />. Of course, since it is an
            abstracted sensor, the entry for 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9000&#8221;</literal></emphasis> is NULL.</para>
          </section>
          
          <section xml:id="sec_power_supply_sensors">
            <title>Power Supply Sensors</title>
      
            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_power_supply_sensors" 
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>Platforms with multiple software
                    visible power supply sensors must implement them as defined RTAS sensors
                    with the token value of 9004, which returns the values defined in 
                    <xref linkend="dbdoclet.50569332_74695" />.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
      
            
            <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_74695">
              <title>Power Supply Sensor Values</title>
              <tgroup cols="2">
                <colspec colname="c1" colwidth="50*" />
                <colspec colname="c2" colwidth="50*" />
                <thead>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">Value</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Status</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>Not present</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>Present and Not operational</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>2</para>
                    </entry>
                    <entry>
                      <para>Status unknown</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>3</para>
                    </entry>
                    <entry>
                      <para>Present and operational</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>For static 9004 sensors, the maxindex in the 
            <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property for the token
            9004 indicates the number of power supplies supported by the platform. In
            this case, the property 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9004&#8221;</literal></emphasis> in the
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node contains the location code for each
            index.</para>
            <para>For dynamic 9004 sensors, the platform provides the information
            about the 9004 indicators as it would for other dynamic sensors. That is,
            the platform does not provide the 
            <emphasis role="bold"><literal>&#8220;ibm,sensor-9004&#8221;</literal></emphasis> property and instead
            provides the 9004 location code information through the 
            <emphasis>ibm,get-indices</emphasis> RTAS call, and if the 
            <emphasis>ibm,get-indices</emphasis> RTAS call returns an index of all-1's
            for a 9004 indicator, then the 
            <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS call is used to get
            the sensor state, instead of the 
            <emphasis>get-sensor</emphasis> RTAS call.</para>
          </section>
          
          <section xml:id="sec_env_sensors">
            <title>Environmental Sensors</title>
      
            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_env_sensors" 
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>Platforms which want to allow an
                    application to analyze their environmental sensors must provide the
                    property 
                    <emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis> in the
                    <emphasis role="bold"><literal>/rtas</literal></emphasis> node (see 
                    <xref linkend="LoPAR.DeviceTree" />).</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
      
            <para>The values for this property is a list of integers that are the
            token values (token) for the defined environmental sensors and the number
            of sensors (maxindex) for that token which are implemented on the
            platform.</para>
            <para><emphasis role="bold">Architecture Note:</emphasis>
            When a sensor is in the 
            <emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis> property and
            when the sensor token indices are obtained via the 
            <emphasis>ibm,get-indices</emphasis> RTAS call, the indices may not be
            contiguous for that sensor token (that is, any of the indices between 0
            and the maxindex, inclusive, may be missing).</para>
          </section>
          
          <section xml:id="sec_sensor_9005_giqc">
            <title>Sensor 9005 Global Interrupt Queue Control
            State</title>
            <para>The 9005 sensor reports the state of the global interrupt server
            queue logic of the interrupt presentation controller for the specific
            processor making the call (Available Processor Mask (APM) for the PowerPC
            interrupt presentation controller). This is used when varying the
            processor on and off line.</para>
      
            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_sensor_9005_giqc" 
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>Platforms that allow processors to be
                    brought online or be taken offline dynamically must implement the global
                    interrupt queue control sensor with a value of 9005 as specified in 
                    <xref linkend="dbdoclet.50569332_23534" />.</para>
                  </listitem>
             	</varlistentry>
             	
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="sec_sensor_9005_giqc" 
                xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                  <listitem>
                    <para>RThe index value for global interrupt
                    queue control state sensor (9005) must be</para>
                    <para>(2
                    <emphasis>ibm,interrupt-server#-size</emphasis>) - 1- the gserver# of the
                    global queue to be sensed as given in the 
                    <emphasis role="bold"><literal>
                    &#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis> property.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
      
            <para>
            <emphasis role="bold">Note:</emphasis> on platforms that do not report 
            <emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis> property,
            the assumed value of the size of the interrupt server number is 8.</para>
          </section>

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

    <section xml:id="dbdoclet.50569332_19385">
      <title>Power Control</title>
      <para />
    
      <section xml:id="dbdoclet.50569332_45884">
        <title><emphasis>set-power-level</emphasis></title>
        <para>This RTAS call is used to set the power level of a power domain to
        either on or off.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45884" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement the 
                <emphasis>set-power-level</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_41166" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_41166">
                  <title>Argument Call Buffer
                  <emphasis>set-power-level</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>set-power-level</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Power_domain</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token defining the power domain</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Level</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for the desired level for this domain</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <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>990x:Extended Delay</para>
                          <para>where x is a number 0-5 (see text below)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Actual_level</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>The power level actually set</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45884" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis>Power_domain</emphasis> must be a power domain identified in the
                OF device tree.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45884" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis>Level</emphasis> must be 100 for full power and 0 for
                off.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45884" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>set-power-level</emphasis> call
                must return the power level actually set in the 
                <emphasis>Actual_level</emphasis> output parameter.</para>
                <para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
          
                <orderedlist>		      
                  <listitem>
                    <para>The set-power-level(0,0) call, if implemented, removes power
                    from the root domain, turning off power to all domains. The external
                    events which can turn power back on are platform specific. The RTAS
                    primitive power-off also removes power from the system, but permits
                    specifying the events which can turn power back on.</para>
                  </listitem>
          
                  <listitem>
                    <para>The implemented values for the 
                    <emphasis>Level</emphasis> parameter for each power domain are defined in
                    the OF device tree.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_38461">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45884" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The <emphasis>set-power-level</emphasis> RTAS call, when implemented, must
                return either a -2 or a 990x return code if the 
                <emphasis>set-power-level</emphasis> operation specified in the RTAS call
                is going to exceed 1 millisecond in duration (where value of x gives a
                hint as to the duration of the busy; see text).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
             
        <para>A single 
        <emphasis>set-power-level</emphasis> operation may require an extended
        period of time for execution. Following the initiation of the hardware
        operation to change the power level, if the 
        <emphasis>set-power-level</emphasis> call returns prior to successful
        completion of the operation, the call returns either a 
        <emphasis>Status</emphasis> code of -2 or 990x. A 
        <emphasis>Status</emphasis> code of -2 indicates that RTAS may be capable
        of doing useful processing immediately. A 
        <emphasis>Status</emphasis> code of 990x indicates that the platform
        requires an extended period of time, and hints at how much time is
        required. Neither the 990x nor the -2 
        <emphasis>Status</emphasis> codes implies that the platform has initiated
        the operation, but it is expected that the 990x 
        <emphasis>Status</emphasis> is used only if the operation had been
        initiated.</para>
        <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>set-power-level</emphasis> with the same power domain token.
        However, software may issue the 
        <emphasis>set-power-level</emphasis> call again either earlier or later
        than this.</para>
        <para><emphasis role="bold">Software Implementation Note:</emphasis>
        In Requirement 
        <xref linkend="dbdoclet.50569332_38461" />, a return code of -2 or 990x
        may either mean that the operation was initiated but not completed, or
        may mean that the operation was not initiated at all.</para>
        <para><emphasis role="bold">Firmware Implementation Notes:</emphasis></para>
        
        <orderedlist>		      
          <listitem>
            <para>If the RTAS initiates and returns before successful completion
            of the operation, then it needs to handle the split of a 
            <emphasis>set-power-level</emphasis> operation across multiple
            calls.</para>
          </listitem>
  
          <listitem>
            <para>It is the firmware&#8217;s responsibility to not return a 
            <emphasis>Status</emphasis> of 0 (success) until the operation is
            complete, and that may require performing an operation such as a delay
            operation or querying the hardware for power good status. In the former
            case, the firmware needs to save state between the calls to the same
            power domain number, until the operation is complete.</para>
          </listitem>
  
          <listitem>
            <para>The 
            <emphasis>set-power-level</emphasis> RTAS call may be called to set the
            power level of other power domains after the initiation to other domains
            and before the operation to those other domains are complete. If
            necessary, the 
            <emphasis>set-power-level</emphasis> call may return a -2 or 990x 
            <emphasis>Status</emphasis> to those calls without initiating the
            operation, if multiple simultaneous operations are not feasible.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="dbdoclet.50569332_67298">
        <title><emphasis>get-power-level</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67298" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement the 
                <emphasis>get-power-level</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_25657" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_25657">
                  <title>Argument Call Buffer 
                  <emphasis>get-power-level</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>get-power-level</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Power_domain</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token defining the power domain</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <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: Can&#8217;t determine current level</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Level</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>The current power level for this domain</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67298" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis>Power_domain</emphasis> must be a power domain identified in the
                OF device tree.</para>
                <para><emphasis role="bold">Software Implementation Note:</emphasis> The 
                <emphasis>get-power-level</emphasis> call only returns information about
                power levels whose state is readable in hardware. It does not need to
                remember the last set state and return that value.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_79728">
        <title><emphasis>power-off</emphasis></title>
        <para>This primitive turns power off on a system which is equipped to
        perform a software-controlled power off function.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_79728" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis>If software controlled power-off hardware is
                present,</emphasis> the 
                <emphasis>power-off</emphasis> function must turn off power to the
                platform, using the argument call buffer described in 
                <xref linkend="dbdoclet.50569332_40594" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_40594">
                  <title><emphasis>power-off</emphasis> Argument Call Buffer</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>power-off</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>Power_on_mask_hi</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Mask of events that can cause a power on event - event
                          mask values [0:31] (right-justified if the cell size is 64
                          bits)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Power_on_mask_lo</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Mask of events that can cause a power on event - event
                          mask values [32:63] (right-justified if the cell size is 64
                          bits)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>On successful operation, does not return</para>
                          <para>-1: Hardware error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_79728" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis>If software controlled power-off hardware is
                present,</emphasis>
                <emphasis>Power_on_mask,</emphasis> which is passed in two parts to permit
                a possible 64 events even on 32-bit implementations,
                must be a bit mask of power on triggers, or if the 
                <emphasis role="bold"><literal>&#8220;power-on-triggers&#8221;</literal></emphasis> property is absent
                from the 
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node, a value of 0 must be used for 
                <emphasis>Power_on_mask_hi</emphasis> and 
                <emphasis>Power_on_mask_lo</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_79728" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>Platforms must omit the 
                <emphasis role="bold"><literal>&#8220;power-on-triggers&#8221;</literal></emphasis> property from the 
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
                
                <para>
                <emphasis role="bold">Implementation Note:</emphasis> The power on triggers, which
                were removed from this architecture, are documented in the 
                <xref linkend="dbdoclet.50569332_77910" />, for legacy reasons.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_77910">
                  <title>Defined Power On Triggers</title>
                  <tgroup cols="2">
                    <colspec colname="c1" colwidth="50*" />
                    <colspec colname="c2" colwidth="50*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Bit</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Event</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>Power Switch On</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2</para>
                        </entry>
                        <entry>
                          <para>Lid Open</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5</para>
                        </entry>
                        <entry>
                          <para>Wake Button</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>8</para>
                        </entry>
                        <entry>
                          <para>Switch to Battery</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>9</para>
                        </entry>
                        <entry>
                          <para>Switch to AC</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>10</para>
                        </entry>
                        <entry>
                          <para>Keyboard or mouse activity</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Enclosure Closed</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>13</para>
                        </entry>
                        <entry>
                          <para>Ring Indicate</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>14</para>
                        </entry>
                        <entry>
                          <para>LAN Attention</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>15</para>
                        </entry>
                        <entry>
                          <para>Time Alarm</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>16</para>
                        </entry>
                        <entry>
                          <para>Configuration change</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>17</para>
                        </entry>
                        <entry>
                          <para>Service Processor</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_79728" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> If software
                controlled power-off hardware is present, the power-off function must
                prevent reboot in the event of a later external power recovery with the
                platform_auto_power_restart system parameter enabled.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_50770">
        <title><emphasis>ibm,power-off-ups</emphasis></title>
        <para>This RTAS call manages the system power-off function in systems
        which may have power backed up with an Uninterruptible Power Supply
        (UPS).</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_50770" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>For platforms that support a platform
                controlled Uninterruptible Power Supply (UPS), the 
                <emphasis>ibm,power-off-ups</emphasis> function must be implemented,
                whether a platform controlled UPS is present or not, using the argument
                call buffer described in 
                <xref linkend="dbdoclet.50569332_63746" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_63746">
                  <title>Argument Call Buffer
                  <emphasis>ibm,power-off-ups</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,power-off-ups</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>On successful operation, does not return</para>
                          <para>-1: Hardware error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_50770" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>If a platform controlled UPS is present,
                then the
                <emphasis>ibm,power-off-ups</emphasis> RTAS call must turn off system
                power while enabling platform auto restart upon restoration of system
                power, according to the platform_auto_power_restart policy described in 
                <xref linkend="dbdoclet.50569332_99524" />, and must not return,
                otherwise, the call must not turn off system power and must not
                return.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_50770" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>If a platform controlled UPS is not
                present, then the 
                <emphasis>ibm,power-off-ups</emphasis> RTAS call must turn off system
                power while enabling platform auto restart upon restoration of system
                power, according to the platform_auto_power_restart policy described in 
                <xref linkend="dbdoclet.50569332_99524" />, and must not return,
                otherwise, the call must not turn off system power and must not
                return.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
          <emphasis role="bold">Software Implementation Notes:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>Supporting 
            <emphasis>ibm,power-off-ups</emphasis>, allows a system to be shutdown
            due to a report that the system was running under UPS power for systems
            with a platform managed UPS. As opposed to 
            <emphasis>power-off</emphasis>,
            <emphasis>ibm,power-off-ups</emphasis>, permits the operating system to
            be restarted when power is restored after a loss of external
            power.</para>
          </listitem>
  
          <listitem>
            <para>The report that a system needs to be shutdown due to running
            under a UPS would be given by the platform as an EPOW event with EPOW
            event modifier being given as, 0x02 = Loss of utility power, system is
            running on UPS/Battery, as described in section 
            <xref linkend="LoPAR.Error" />.</para>
          </listitem>
  
          <listitem>
            <para>If the RTAS 
            <emphasis>ibm,power-off-ups</emphasis> call is supported by the platform,
            it will also allow a shutdown with a subsequent restart when power is
            restored for systems running with a UPS that is not under platform
            control. This presumes that the OS has some external means of recognizing
            when running under UPS power to initiate the 
            <emphasis>ibm,power-off-ups</emphasis> call.</para>
          </listitem>
        </orderedlist>		      
        
      </section>

    </section>

    <section>
      <title>Reboot and Flash Update Calls</title>
      <para>During execution, it may become necessary to shut down processing
      and reboot the system in a new mode. For example, a different OS level
      may need to be loaded, or the same OS may need to be rebooted with
      different settings of System Environment Variables.</para>
    
      <section xml:id="dbdoclet.50569332_50284">
        <title><emphasis>system-reboot</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_50284" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement a 
                <emphasis>system-reboot</emphasis> call which resets all processors and
                all attached devices. After reset, the system must be booted with the
                current settings of the System Environment Variables (refer to 
                <xref linkend="LoPAR.Platform" /> for more information).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_50284" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The RTAS 
                <emphasis>system-reboot</emphasis> call must be implemented using the
                argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_20680" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20680">
                  <title>Argument Call Buffer
                  <emphasis>system-reboot</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>system-reboot</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>On successful operation, does not return</para>
                          <para>-1: Hardware error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para><emphasis role="bold">Hardware Implementation Note:</emphasis> 
        The platform must be able to perform
        a system reset and reboot. On a multiprocessor system, this should be a
        hard reset to the processors.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_77103">
        <title><emphasis>ibm,update-flash-64-and-reboot</emphasis></title>
        <para>The 
        <emphasis>ibm,update-flash-64-and-reboot</emphasis> function is described
        in this section. It does not return to the OS if successful. This call
        supports RTAS instantiated in 32 bit mode to access storage at addresses
        above 4GB. In an exception to the LPAR Requirement 
        <xref linkend="LoPAR.Virtualization" /> this call supports block lists
        being outside of the Real Mode Area (RMA) as long as the initial block
        list is at an address below the limits of the cell size of the 
        <emphasis>Block_list</emphasis> argument.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The argument call buffer for the 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call must
                correspond to the definition in 
                <xref linkend="dbdoclet.50569332_14715" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14715">
                  <title>Argument Call Buffer
                  <emphasis>ibm,update-flash-64-and-reboot</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,update-flash-64-and-reboot</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>Block_list</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>A real pointer to a block list of 64 bit entries</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>-1: Hardware error</para>
                          <para>-3: Image unacceptable to update program</para>
                          <para>-4: Programming failed when partially complete, and the
                          flash is now corrupted - reboot may fail</para>
                          <para>-9002: Not authorized</para>
                        </entry>
                      </row>
                      <row>
                        <entry nameend="c3" namest="c1">
                          <para>The 
                          <emphasis>Status</emphasis> of 0 is never returned, because this
                          RTAS call does not return if successful.</para>
                        </entry>
                      </row>
                      <row>
                        <entry nameend="c3" namest="c1">
                          <para>The -1 return is to cover the case where some condition
                          prevents RTAS from being able to program the flash at this
                          time. For example, the flash programming power supply is
                          disconnected, a low-level security check (for instance a switch
                          or jumper) fails, or a test programming probe fails for an
                          unknown reason or the case where the flash has been
                          successfully updated, but the reboot fails for some
                          reason.</para>
                        </entry>
                      </row>
                      <row>
                        <entry nameend="c3" namest="c1">
                          <para>The -3 return is to cover the case where embedded
                          vendor/platform specific information in the image failed to
                          conform to the required format or content for this platform,
                          such as the firmware revision number or a CRC or some other
                          check which was intended to ensure the integrity of the
                          image.</para>
                        </entry>
                      </row>
                      <row>
                        <entry nameend="c3" namest="c1">
                          <para>The -4 return is to cover the case where the update
                          failed before the image was fully updated. In this case, the OS
                          has the responsibility for reporting the failure.</para>
                        </entry>
                      </row>
                      <row>
                        <entry nameend="c3" namest="c1">
                          <para>The -9002 return code is used to indicate that the
                          partition at the time the call was made was not authorized to
                          update the flash image.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The RTAS 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> call 
                <emphasis>Block_list</emphasis> on platforms that do not present the 
                <emphasis role="bold"><literal>&#8220;ibm,flash-block-version&#8221;</literal></emphasis> property in the
                OF 
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node must conform to the definition shown in 
                <xref linkend="dbdoclet.50569332_53334" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_53334">
                  <title>Format of Block List</title>
                  <tgroup cols="1">
                    <colspec colname="c1" colwidth="100*" />
                    <thead>
                      <row>
                        <entry>
                          <para>Length of 
                          <emphasis>Block_list</emphasis> in bytes</para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>Address of memory area 1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Length of memory area 1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>. . .</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Address of memory area n</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Length of memory area n</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call 
                <emphasis>Block_list</emphasis> must be a sequence of 64 bit cells.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>Memory blocks referenced in the 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call 
                <emphasis>Block_list</emphasis> must reside in System Memory outside that
                reserved for firmware (both the RTAS data area and OF&#8217;s memory
                defined by real-base and real-size).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The block list referenced by the 
                <emphasis>Block_list</emphasis> argument to the 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call must be in
                System Memory below the maximum address supported by the RTAS
                instantiated cell size.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>The addresses of memory blocks referenced
                by the 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call 
                <emphasis>Block_list</emphasis> must align tn a 4 KB boundary.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para>A memory block, included in the 
                <emphasis>ibm,update-flash-64-and-reboot</emphasis> RTAS call 
                <emphasis>Block_list,</emphasis> must not cross a 256MB boundary.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_77103" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,update-flash-64-and-reboot</emphasis> call must test the
                image to make sure it has the right format and is not damaged, update the
                flash from the 
                <emphasis>Block_list</emphasis> and then perform a system reset and
                reboot, as for the 
                <emphasis>system-reboot</emphasis> call.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Hardware and Software Implementation Note:</emphasis> Platform
        specific information should be embedded in the flash images to identify
        the firmware unambiguously and to ensure that the firmware operates
        correctly on the platform. Such information might include platform board
        model and revision numbers covered by the firmware, manufacturer ID, and
        firmware revision number used for external display. This information
        should include a CRC or other check which ensures the integrity of the
        data.</para>
        <para>
          <emphasis role="bold">Software Implementation Notes:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>The execution time for this calls may be in the order of
            seconds, rather than &#8220;a few tens of microseconds&#8221; as noted on
            page 
            <xref linkend="dbdoclet.50569332_12814" xrefstyle="select: pagenumber"/>.</para>
          </listitem>
  
          <listitem>
            <para>The RTAS flash update programs should display progress,
            completion, and error information while the flash update is underway, if
            possible.</para>
          </listitem>
  
          <listitem>
            <para>The OS does not expect a return from the 
            <emphasis>ibm,update-flash-64-and-reboot</emphasis> call other than for
            cases where the hardware cannot be accessed, the flash image is
            unacceptable to the RTAS flash update program, the result of the update
            corrupted the flash, or the platform could not be rebooted.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="sec_flash_update_discont">
        <title>Flash Update with Discontiguous Block Lists</title>
        <para>The property 
        <emphasis role="bold"><literal>&#8220;ibm,flash-block-version&#8221;</literal></emphasis> (see 
        <xref linkend="LoPAR.DeviceTree" />) is defined to describe the
        following definition and operation of the 
        <emphasis>Block_list</emphasis> shown in 
        <xref linkend="dbdoclet.50569332_71043" />.</para>
        
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71043">
          <title>Format of Discontiguous 
          <emphasis>Block_list</emphasis></title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="50*" />
            <colspec colname="c2" colwidth="50*" />
            <thead>
              <row>
                <entry>
                  <para>VER</para>
                </entry>
                <entry>
                  <para>Length of 
                  <emphasis>Block_list</emphasis> in bytes</para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Address of 
                  <emphasis>Block_list</emphasis> extension</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Address of memory area 1</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Length of memory area 1</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Address of memory area 2</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Length of memory area 2</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>- - -</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Address of memory area n</para>
                </entry>
              </row>
              <row>
                <entry nameend="c2" namest="c1">
                  <para>Length of memory area n</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Where:</para>
        
        <itemizedlist>		      
          <listitem>
            <para>VER (1 byte in length) indicates the version of the 
            <emphasis>Block_list</emphasis>.</para>
          </listitem>
          
          <listitem>
            <para>Length of the 
            <emphasis>Block_list</emphasis> in bytes indicates the size of this 
            <emphasis>Block_list</emphasis>, including the header cell and the cell
            with the address of the 
            <emphasis>Block_list</emphasis> extension.</para>
          </listitem>
          
          <listitem>
            <para>Address of the 
            <emphasis>Block_list</emphasis> extension indicates the location of the
            next 
            <emphasis>Block_list</emphasis>. 0x00 indicates no additional 
            <emphasis>Block_list</emphasis> extension.</para>
          </listitem>
          
          <listitem>
            <para>Address of memory area 1 (2 . . . n) indicates the location of
            this portion of the flash image.</para>
          </listitem>
          
          <listitem>
            <para>Length of memory area 1 (2 . . . n) indicates the length of this
            portion of the flash image.</para>
          </listitem>
        </itemizedlist>		      
        
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_flash_update_discont" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>If VER is 0x01, the 
                <emphasis>Block_list</emphasis> must be formatted as in 
                <xref linkend="dbdoclet.50569332_71043" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_flash_update_discont" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>If VER is 0x01, the 
                <emphasis>Block_list</emphasis> parameter in the function call or the
                Address of the 
                <emphasis>Block_list</emphasis> extension, if not 0x00, must point to a 
                <emphasis>Block_list</emphasis> cell containing VER and Length of the 
                <emphasis>Block_list</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_flash_update_discont" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>If VER is 0x01, the Address of the 
                <emphasis>Block_list</emphasis> extension parameter must be 0x00 to
                indicate that there are no further extensions.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_flash_update_discont" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The VER byte must exist in the 
                <emphasis>Block_list</emphasis> and in each 
                <emphasis>Block_list</emphasis> extension.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_flash_update_discont" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>If the platform supports the property 
                <emphasis role="bold"><literal>&#8220;ibm,flash-block-version&#8221;</literal></emphasis> with value
                0x01, it must also support the default value 0x00.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>The 
        <emphasis>Block_list</emphasis> format allows flexibility in the size and
        page requirements for the block lists. Page alignment is not required for
        the lists or extensions. They may run across contiguous pages with the
        control being the length of each list or extension and with the end being
        the 0x00 pointer.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_81833">
        <title><emphasis>ibm,manage-flash-image</emphasis></title>
        
        <para>The 
        <emphasis>ibm,manage-flash-image</emphasis> RTAS call supports systems
        having a &#8220;temporary&#8221; and &#8220;permanent&#8221; flash image
        areas. It allows the user to commit the temporary flash image by copying
        it to the permanent image area. It also allows the user to reject the
        temporary flash image by overwriting it with the permanent flash
        image.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81833" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The RTAS 
                <emphasis>ibm,manage-flash-image</emphasis> call must be implemented using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_55815" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55815">
                  <title>Argument Call Buffer
                  <emphasis>ibm,manage-flash-image</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for ibm,manage-flash-image</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="0">
                          <para>
                            <emphasis>Image to Commit</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>0: Reject &#8220;temporary&#8221; firmware image</para>
                          <para>1: Commit &#8220;temporary&#8221; firmware image</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="0">
                          <para>Out</para>
                        </entry>
                        <entry morerows="0">
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Busy</para>
                          <para>-3: Parameter Error</para>
                          <para>-9001: Cannot Overwrite the Active Firmware Image
                          Error</para>
                          <para>-9002 Not Authorized</para>
                          <para>990x: Extended Delay</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81833" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,manage-flash-image</emphasis> RTAS call must not change the
                system flash and must return a 
                <emphasis>Status</emphasis> of value -9001 when called with a request to
                reject the temporary firmware image when not running on the permanent
                firmware image.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81833" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,manage-flash-image</emphasis> RTAS call must not change the
                system flash and must return a 
                <emphasis>Status</emphasis> of value -9001 when called with a request to
                commit the temporary firmware image when not running on the temporary
                firmware image.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Platform Implementation Note:</emphasis> In platforms supporting
        two firmware image areas, platforms always apply updates to the temporary
        image area. The RTAS call 
        <emphasis>ibm,manage-flash-image</emphasis> is the normal means by which a
        temporary image is committed to the permanent side. However, if a
        platform is running from a temporary image when an update is to be
        applied, then the platform may automatically commit the current temporary
        image to the permanent side to allow the new image to be updated to the
        temporary image area. The 
        <emphasis>ibm,validate-flash-image</emphasis> RTAS call is used to
        determine what would result from an attempt to update a FLASH image
        taking in to account the image to be updated and the current image being
        executed.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_40640">
        <title><emphasis>ibm,validate-flash-image</emphasis></title>
        
        <para>The 
        <emphasis>ibm,validate-flash-image</emphasis> RTAS call allows OS service
        code to determine if a candidate flash image is valid, if the partition
        has authority to update the flash image, and what the resulting flash
        levels will be after performing the update.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,validate-flash-image RTAS</emphasis> call must be
                implemented using the argument call buffer described in 
                <xref linkend="dbdoclet.50569332_35397" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_35397">
                  <title>Argument Call Buffer
                  <emphasis>ibm,validate-flash-image</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for
                          <emphasis>ibm,validate-flash-image</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer Ptr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of minimum 4 K buffer, contiguous in real
                          memory</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Buffer Size</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Size in bytes of Buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Out</para>
                        </entry>
                        <entry morerows="0">
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>990x: Extended Delay</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Busy</para>
                          <para>-3: Parameter Error</para>
                          <para>-9002: Not authorized</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Update Results Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token to identify what will happen if update is attempted
                          with this token, described in Requirement 
                          <xref linkend="dbdoclet.50569332_72032" />.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_71844">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,validate-flash-image RTAS</emphasis> call 
                <emphasis>Buffer Ptr</emphasis> parameter must be a real address
                representing the starting address of a minimum 4 K buffer, contiguous in
                real memory.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>On input, the 
                <emphasis>ibm,validate-flash-image RTAS</emphasis> call buffer pointed to
                by the 
                <emphasis>Buffer Ptr</emphasis> parameter must contain the first 4 KB of
                the candidate flash image to be validated.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The 
                <emphasis>ibm,validate-flash-image RTAS</emphasis> call buffer described
                in Requirement 
                <xref linkend="dbdoclet.50569332_71844" /> must be in the partition's
                RMA.</para>
               </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_83954">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
               <para>On exit from the 
                <emphasis>ibm,validate-flash-image RTAS</emphasis> call, RTAS must place
                the following data in the buffer, starting at the address in the 
                <emphasis>Buffer Ptr</emphasis> parameter:</para>
                
                <itemizedlist>		      
                  <listitem>
                    <para>&#8220;MI&#8221;&lt;sp&gt; current-T-image &lt;sp&gt;
                    current-P-image &lt;0x0A&gt;</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;MI&#8221;&lt;sp&gt; new-T-image &lt;sp&gt; new-P-image
                    &lt;0x00&gt;</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;ML&#8221;&lt;sp&gt; current-T-image
                    &lt;sp&gt; current-P-image &lt;0x0A&gt;</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;ML&#8221;&lt;sp&gt; new-T-image &lt;sp&gt;
                    new-P-image &lt;0x00&gt;</para>
                  </listitem>

                  <listitem>
                    <para>&#8220;MG&#8221;&lt;sp&gt;current-T-img-ga-date&lt;sp&gt;current-P-img-ga-date&lt;0x0A&gt;</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;MG&#8221;&lt;sp&gt;new-T-img-ga-date&lt;sp&gt;new-P-img-ga-date&lt;0x0A&gt;</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;MG&#8221;&lt;sp&gt;input-image-ga-date&lt;0x0A&gt;</para>
                  </listitem>

                  <listitem>
                    <para>&#8220;ME&#8221;&lt;sp&gt;fw-service-entitlement-expiration-date&lt;0x00&gt;</para>
                  </listitem>
                </itemizedlist>		      
                
                <para>In Requirement 
                <xref linkend="dbdoclet.50569332_83954" />, current-T-image and
                current-P-image are the fixpack microcode image names currently on the
                Temporary and Permanent sides, respectively, and new-T-image and
                new-P-image are the fixpack microcode image names that will exist in
                flash after a successful flash update with the candidate image.</para>
                <para>If the current flash image level is not known, the value provided
                for current-T-image and/or current-P-image is
                &#8220;UNKNOWN&#8221;.</para>
                <para>If the flash update function would not succeed, the values of
                new-T-image and new-P-image are the same as current-T-image and
                current-P-image, respectively.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_72032">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40640" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>On exit from the 
                <emphasis>ibm,validate-flash-image RTAS</emphasis> call, the 
                <emphasis>Update Results Token</emphasis> output must be updated with one
                of the values in 
                <xref linkend="dbdoclet.50569332_52431" />. This list is in order;
                firmware must provide the first value in the list which would be true if
                an update is attempted:</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_52431">
                  <title>Update Results Token Values</title>
                  <tgroup cols="2">
                    <colspec colname="c1" colwidth="50*" />
                    <colspec colname="c2" colwidth="50*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Description</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>1</para>
                        </entry>
                        <entry>
                          <para>No update done, partition does not have authority to
                          perform flash update</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>2</para>
                        </entry>
                        <entry>
                          <para>No update done, the candidate image is not valid for this
                          platform</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>3</para>
                        </entry>
                        <entry>
                          <para>Current fixpack level is unknown, the new-T-image and
                          new-P-image identifies show what will exist in flash after
                          update with this image</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Current T side will be committed to P side before being
                          replace with new image, and the new image is downlevel from
                          current image</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5</para>
                        </entry>
                        <entry>
                          <para>Current T side will be committed to P side before being
                          replaced with new image</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>6</para>
                        </entry>
                        <entry>
                          <para>T side will be updated with a downlevel image</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>7</para>
                        </entry>
                        <entry>
                          <para>No update done, the candidate image's release date is later 
                          than the system's firmware service entitlement date - service 
                          warranty period has expired</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>T side will be updated with a newer or identical
                          image</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_28163">
        <title><emphasis>ibm,activate-firmware</emphasis></title>
        
        <para>The 
        <emphasis>ibm,activate-firmware</emphasis> allows an OS to activate a new
        version of firmware that has been updated in the platform flash memory
        after the partition was started.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28163" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,activate-firmware</emphasis> RTAS call must be implemented
                using the argument call buffer described in 
                <xref linkend="dbdoclet.50569332_51420" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_51420">
                  <title>Argument Call Buffer
                  <emphasis>ibm,activate-firmware</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for
                          <emphasis>ibm,activate-firmware</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number of Outputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="0">
                          <para>Out</para>
                        </entry>
                        <entry morerows="0">
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>990x: Extended Delay</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Busy, try again later</para>
                          <para>-3: Parameter Error</para>
                          <para>-9001: No valid FW available to activate</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Software implementation Note:</emphasis> The OS should expect
        that a number of calls may be required to accomplish firmware activation,
        with &#8220;Busy, try again later&#8221; or &#8220;Extended Delay&#8221;
        return codes from all but the last call. The new version of firmware is
        not in use until a &#8220;Success&#8221; return. The OS may interleave
        calls to other RTAS functions between calls to this function.</para>
      </section>

    </section>
    
    <section xml:id="dbdoclet.50569332_36251">
      <title>SMP Support</title>
      <para>In a Symmetric Multiprocessor (SMP) system, the platform needs the
      ability to synchronize the clocks on all the processors. The timebase
      registers are synchronized by the platform before CPUs are given to the
      OS.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_36251" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis>(Merged into Requirement 
              <xref linkend="LoPAR.Platform" />)</emphasis></para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_40371">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_36251" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis>(Merged into Requirement 
              <xref linkend="LoPAR.Platform" />)</emphasis></para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="dbdoclet.50569332_68497">
        <title><emphasis>stop-self</emphasis></title>
        
        <para>The stop-self primitive causes a processor thread to stop
        processing OS or user code, and to enter a state in which it is only
        responsive to the 
        <emphasis>start-cpu</emphasis> RTAS primitive. This is referred to as the 
        RTAS 
        <emphasis>stopped</emphasis> state.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68497" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>A <emphasis>stop-self</emphasis> RTAS call must place the calling processor
                thread in the 
                RTAS 
                <emphasis>stopped</emphasis> state. This call must be implemented using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_32280" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68497" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>RTAS must insure that a processor thread
                in the RTAS 
                <emphasis>stopped</emphasis> state does not checkstop or otherwise fail if
                a machine check or soft reset exception occurs. Processor threads in this
                state receive the exception, but must perform a null action and remain in
                the RTAS 
                <emphasis>stopped</emphasis> state.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_32280">
                  <title>Argument Call Buffer
                  <emphasis>stop-self</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>stop-self</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>If successful, this call does not return</para>
                          <para>-1: Hardware Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>Software Implementation Note: If this call succeeds, it does not
                return. The CPU thread waits for some other processor thread to issue a 
                <emphasis>start-cpu</emphasis> targeted to this processor thread.</para>
                <para>
                <emphasis role="bold">Firmware Implementation Note:</emphasis> In an LPAR environment
                the state of the interrupt sub-system associated with this processor on
                entry to this call cannot be trusted. Although interrupts are masked as
                part of the RTAS call protocol, the caller may have left the processor
                configured as an interrupt server. Therefore, interrupt signals may be
                pending within the processor&#8217;s interrupt management area. These
                conditions need to be cleared prior to allocating this processor to
                another partition.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_82698">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68497" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>Platforms which support the enhanced 
                <emphasis>stop-self</emphasis> RTAS behavior must include the name only 
                <emphasis role="bold"><literal>&#8220;ibm,integrated-stop-self&#8221;</literal></emphasis> OF property,
                under the 
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node, and prior to placing a processor in the
                stopped state, flush and disable any caches/memory exclusively used by
                the issuing processor.</para>
                <para>
                <emphasis role="bold">Architecture Note:</emphasis> In Requirement 
                <xref linkend="dbdoclet.50569332_82698" />, an exclusively used cache
                means that no other running processor currently needs the cache for
                normal operation, even if the cache could potentially be shared with
                other processors. An exclusively used memory means any main memory
                allocated local to the processor thread and thus not accessible by other
                processor threads.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68497" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>Execution of the 
                <emphasis>stop-self</emphasis> call by the last active processor thread
                must cause the firmware to recover all the resources owned by the
                executing OS image for use per platform policy.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_39014">
        <title><emphasis>start-cpu</emphasis></title>
        
        <para>The start-cpu primitive is used to cause a processor thread which
        is currently in the RTAS
        stopped state to start processing at an indicated location.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39014" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>A <emphasis>start-cpu</emphasis> RTAS call must remove the processor thread
                specified by the 
                <emphasis>CPU_id</emphasis> parameter from the RTAS 
                <emphasis>stopped</emphasis> state. This call must be implemented using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_41442" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39014" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The processor thread specified by the 
                <emphasis>CPU_id</emphasis> parameter must be in the RTAS 
                <emphasis>stopped</emphasis> state entered because of a prior call by that
                processor to the 
                <emphasis>stop-self</emphasis> primitive.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39014" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>When a processor thread exits the RTAS 
                <emphasis>stopped</emphasis> state, it must begin execution in real mode,
                with the MSR in the same state as from a system reset interrupt (except
                for the MSR<subscript>HV</subscript> bit which is on if not running under a hypervisor
                and off if running under a hypervisor) at the real location indicated by
                the 
                <emphasis>Start_location</emphasis> parameter, with register R3 set to the
                value of parameter 
                <emphasis>Register_R3_contents</emphasis> and the MSR as defined in 
                <xref linkend="dbdoclet.50569332_25774" />. All other register contents
                are indeterminate.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_41442">
                  <title>Argument Call Buffer
                  <emphasis>start-cpu</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>start-cpu</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>Cpu_id</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token identifying the processor thread to be started,
                          obtained from the value of the
                          <emphasis role="bold"><literal>
                          &#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property for
                          the CPU in the OF device tree</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Start_location</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address at which the designated CPU begins
                          execution</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Register_R3_contents</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Value which is loaded into Register R3 before beginning
                          execution at Start_location</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>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Note:</emphasis> Requirement 
        <xref linkend="LoPAR.Platform" /> applies to the start-cpu RTAS
        call. At the completion of start-cpu, the caches to be used by the
        specified processor must have been initialized and the state bits made
        accurate prior to beginning execution at the start address.</para>
   
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_25774">
          <title>Machine State Register (MSR) State in Started
          Processor</title>
          <tgroup cols="6">
            <colspec colname="c1" colwidth="16*" />
            <colspec colname="c2" colwidth="16*" />
            <colspec colname="c3" colwidth="16*" />
            <colspec colname="c4" colwidth="16*" />
            <colspec colname="c5" colwidth="16*" />
            <colspec colname="c6" colwidth="16*" />
            <thead>
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Bit Number</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Name</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Initial Value upon start by
                    start-cpu</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Bit Number</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Name</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Initial Value upon start by
                    start-cpu</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>SF</para>
                </entry>
                <entry>
                  <para>0 if RTAS instantiated in 32 bit mode 1 if RTAS
                  instantiated in 64 bit mode</para>
                </entry>
                <entry>
                  <para>53</para>
                </entry>
                <entry>
                  <para>SE</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>54</para>
                </entry>
                <entry>
                  <para>BE</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>2</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>55</para>
                </entry>
                <entry>
                  <para>FE1</para>
                </entry>
                <entry>
                  <para>Implementation Dependent</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>3</para>
                </entry>
                <entry>
                  <para>HV</para>
                </entry>
                <entry>
                  <para>0 if running under hypervisor firmware, 1 if running in
                  &#8220;SMP&#8221; mode</para>
                </entry>
                <entry>
                  <para>56</para>
                </entry>
                <entry>
                  <para>US</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>4:46</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>57</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>47</para>
                </entry>
                <entry>
                  <para>ILE</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>58</para>
                </entry>
                <entry>
                  <para>IR</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>48</para>
                </entry>
                <entry>
                  <para>EE</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>59</para>
                </entry>
                <entry>
                  <para>DR</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>49</para>
                </entry>
                <entry>
                  <para>PR</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>60</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>50</para>
                </entry>
                <entry>
                  <para>FP</para>
                </entry>
                <entry>
                  <para>Implementation Dependent</para>
                </entry>
                <entry>
                  <para>61</para>
                </entry>
                <entry>
                  <para>PMM</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>51</para>
                </entry>
                <entry>
                  <para>ME</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>62</para>
                </entry>
                <entry>
                  <para>RI</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>52</para>
                </entry>
                <entry>
                  <para>FE0</para>
                </entry>
                <entry>
                  <para>Implementation Dependent</para>
                </entry>
                <entry>
                  <para>63</para>
                </entry>
                <entry>
                  <para>LE</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
      
      <section xml:id="dbdoclet.50569332_81575">
        <title><emphasis>query-cpu-stopped state</emphasis></title>
        
        <para>The query-cpu-stopped-state primitive is used to query a different
        processor thread to determine its status with respect to the RTAS stopped
        state.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81575" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>A <emphasis>query-cpu-stopped-state</emphasis> RTAS call must return the 
                <emphasis>CPU_status</emphasis> of the processor thread specified by the 
                <emphasis>Cpu_id</emphasis> parameter. This call must be implemented using
                the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_17977" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_17977">
                  <title>Argument Call Buffer
                  <emphasis>query-cpu-stopped-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 morerows="3">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>query-cpu-stopped-state</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Cpu_id</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token identifying the processor thread to be queried,
                          obtained from the value of the
                          <emphasis role="bold"><literal>
                          &#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property for
                          the CPU in the OF device tree</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-2: Hardware Busy, Try again later</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>CPU_status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: The processor thread is in the RTAS stopped
                          state</para>
                          <para>1: 
                          <emphasis>stop-self</emphasis> is in progress</para>
                          <para>2: The processor thread is not in the RTAS stopped
                          state</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Firmware Implementation Note:</emphasis> RTAS serialization may
        be required between the
        <emphasis>stop-self</emphasis> and the 
        <emphasis>query-cpu-stopped-state</emphasis> calls.</para>
        <para>
        <emphasis role="bold">Software Implementation Note:</emphasis> The OS performs a 
        <emphasis>stop-self</emphasis> on the desired processor thread, then
        periodically call
        <emphasis>s query-cpu-stopped-state</emphasis> on another processor thread
        until the desired processor thread is stopped. Before calling 
        <emphasis>set-power-level</emphasis> to power off the desired processor,
        or isolate the logical CPU, the platform requires that all processor
        threads be in the RTAS stopped state.</para>
      </section>

    </section>

    <section>
      <title>Miscellaneous RTAS Calls</title>
      <para />
    
      <section xml:id="dbdoclet.50569332_42118">
        <title><emphasis>ibm,os-term</emphasis></title>
        
        <para>This RTAS call is provided for the OS to indicate to the platform
        that it has terminated normal operation. A string of information is
        passed to the platform.</para>
        <para>A call to the 
        <emphasis>ibm,os-term</emphasis> RTAS function implies the following to
        the platform:</para>
        
        <itemizedlist>		      
          <listitem>
            <para>Any platform reporting and recovery policies may now take
            effect.</para>
          </listitem>
          
          <listitem>
            <para>The OS may no longer be issuing periodic 
            <emphasis>event-scan</emphasis> requests, so surveillance monitoring does
            not continue.</para>
          </listitem>
          
          <listitem>
            <para>All devices not marked 
            <emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> are released by the OS
            (including, for example, native serial ports used by a service
            processor).</para>
          </listitem>
          
          <listitem>
            <para>The OS no longer responds to any EPOW events, so it is up to the
            platform to take any appropriate actions for such events.</para>
          </listitem>
        </itemizedlist>		      
          
        <para>Due to the above implications, the platform may take actions (for
        example, a service processor &#8220;call home&#8221;) that could conflict
        with normal processing of further RTAS requests. However, since the OS
        has entered a &#8220;live halt&#8221; state, the list of RTAS functions
        that it still needs is relatively small. The list of RTAS functions that
        the platform might expect to see after 
        <emphasis>ibm,os-term</emphasis> includes:</para>
        
        <itemizedlist>		      
          <listitem>
            <para><emphasis>nvram-fetch</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>nvram-store</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>display-character</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>power-off</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>ibm,power-off-ups</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>system-reboot</emphasis></para>
          </listitem>
          
          <listitem>
            <para><emphasis>check-exception</emphasis> for machine checks (Although the OS
            may still react normally to a machine check condition by calling 
            <emphasis>check-exception</emphasis>, it might not process a returned
            error log. It is allowable for 
            <emphasis>check-exception</emphasis> to not return an extended log when in
            this state.)</para>
          </listitem>
        </itemizedlist>		      
        
        <para>If a platform has a service processor, and a policy has been
        established for actions to be taken by the service processor upon
        receiving notice of OS termination, the service processor may complete
        those actions and a return to the CPU from this call may never occur. If
        the call does return, the OS performs its own termination policy.</para>
        
        <para>When the platform supports extended 
        <emphasis>ibm,os-term</emphasis> behavior, the return to the RTAS will
        always occur unless there is a kernel assisted dump active as initiated
        by an 
        <emphasis>ibm,configure-kernel-dump</emphasis> call.</para>
        <para>Platforms capable of supporting this extended 
        <emphasis>ibm,os-term</emphasis> behavior will so indicate by presenting
        the 
        <emphasis role="bold"><literal>&#8220;ibm,extended-os-term&#8221;</literal></emphasis> RTAS property in
        the OF device tree.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_42118" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>RTAS must implement an 
                <emphasis>ibm,os-term</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_38756" /> to receive a termination string
                from the OS.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_38756">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,os-term</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,os-term</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>Pointer to String</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>NULL terminated string</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="0">
                          <para>Out</para>
                        </entry>
                        <entry morerows="0">
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>0:success</para>
                          <para>-1:hardware error</para>
                          <para>-2:hardware busy, try again later</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Platform Implementation Note:</emphasis> The string should be
                maintained in an error log which could be made accessible to a service
                location or saved in the platform for later remote access.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_42118" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,os-term</emphasis> call must disable surveillance.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_42118" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>During the machine check and soft reset
                handlers, the platform must support access to the 
                <emphasis>ibm,os-term</emphasis> RTAS function.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_42118" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If the 
                <emphasis>ibm,os-term</emphasis> call does not return to the caller, the
                platform must honor the partition_auto_restart system parameter
                value.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_42118" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>For platforms supporting extended 
                <emphasis>ibm,os-term</emphasis> behavior, the 
                <emphasis>ibm,os-term</emphasis> call must always return unless there is
                an active kernel assisted dump configured as specified by an 
                <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Platform implementation note:</emphasis> The 
        <emphasis>ibm,os-term</emphasis> RTAS call allows for the case where the
        OS and platform may share an I/O device such as a TTY where the OS would
        have use of the device normally, and the platform use when the OS has
        terminated, such as to implement an error reporting call home function
        both in the OS and the platform. For proper sharing in such a case where
        extended behavior is supported, when the primary partition console is
        also used for the call-home by the platform, the platform should not
        initiate the call home until after the partition shuts down.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_19739">
        <title><emphasis>Ibm,exti2c</emphasis></title>
        
        <para>For support of platforms which require an external 
        I<superscript>2</superscript>C bus, a special port to the service processor is
        required. The EXTI2C option is designed to control specific external
        devices. Designers cannot assume that an arbitrary 
        I<superscript>2</superscript>C device may be substituted.</para>
        <para>The 
        <emphasis>ibm,exti2c</emphasis> call provides a single channel to the 
        I<superscript>2</superscript>C bus. Through this channel, software can read or
        write up to 256 bytes from/to an addressed resource within an address
        space between X&#8217;000000 and X&#8217;FFFFFF. Reference the
        specification for the specific I<superscript>2</superscript>C device to determine what effect such operations
        may have.</para>
        <para>The Buffer Pointer argument is used to manage this channel across
        multiple
        <emphasis>ibm,exti2c</emphasis> RTAS calls. If the input Buffer Pointer
        value on a call is zero, the state of the channel is reset and any
        outstanding I<superscript>2</superscript>C operation is aborted. If the input Buffer Pointer
        has a different value from that of the last call, a new operation is
        started, with any previous operation being aborted. An input Buffer
        Pointer value that is the same as that used on the previous call
        indicates a continuation of the last operation, given that the 
        <emphasis>Status</emphasis> of the last call was not 0 (success) or -1
        (hardware error). These terminating statuses reset the channel.</para>
        <para>Using software must manage serialization to the 
        <emphasis>ibm,exti2c</emphasis> channel across multiple calls for the same
        I<superscript>2</superscript>C operation.</para>
        <para>A single 
        <emphasis>ibm,exti2c</emphasis> operation may require an extended period
        of processing by background hardware. During this time, RTAS returns
        either a 
        <emphasis>Status</emphasis> code of -2 or 990x. A 
        <emphasis>Status</emphasis> of -2 indicates that RTAS may be capable of
        doing useful processing immediately.</para>
        <para>A 
        <emphasis>Status</emphasis> code of 990x indicates that the platform
        requires an extended period of time to perform the operation. It is
        suggested that software delay for 10 raised to the x milliseconds before
        calling
        <emphasis>ibm,exti2c</emphasis> with the same Buffer Pointer value,
        however, software may call again earlier or later.</para>
        <para>A 
        <emphasis>Status</emphasis> code of -1 indicates either a general error
        associated with the local 
        I<superscript>2</superscript>C hardware (service processor) or that the channel
        has been corrupted due to other error conditions not associated with the
        I<superscript>2</superscript>C operation. If the buffer is changed, as when an
        error code is returned, the RTAS 
        <emphasis>Status</emphasis> code is 0 (success).</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> RTAS must implement an 
                <emphasis>ibm,exti2c</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_29660" /> to allow communications with
                special hardware.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_29660">
                  <title>ibm,exti2c Argument Call Buffer</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,exti2c</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>Buffer Pointer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real Address of data buffer</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="0">
                          <para>Out</para>
                        </entry>
                        <entry morerows="0">
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry morerows="0">
                          <para>0:Success</para>
                          <para>-1:hardware error</para>
                          <para>-2:hardware busy, try again later</para>
                          <para>-3: Parameter error</para>
                          <para>990x:Extended delay where x is a number 0-5</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> The Buffer Pointer must point
                to a contiguous real storage area large enough to contain the 
                I<superscript>2</superscript>C command and any associated data (maximum of 261
                bytes).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> The Buffer format for the
                write operation must be as defined in 
                <xref linkend="dbdoclet.50569332_58395" />.</para>
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_58395">
                  <title>EXTI2C Buffer Write Operation Format</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">Condition</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Byte #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Content</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="3">
                          <para>On Call</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>0x00</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                        <entry>
                          <para>Address of I2C resource</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Length of op. (1-255 with 0 specifying 256)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5...</para>
                        </entry>
                        <entry>
                          <para>Data</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="3">
                          <para>On Return - I2C OK</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry morerows="3">
                          <para>Buffer unmodified</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5...</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="2">
                          <para>On Return - I2C error</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>0x01</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                        <entry>
                          <para>Address of I2C resource</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>I2C operation error code</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Firmware and Software Implementation Note:</emphasis> When the 
                <emphasis>ibm,exti2c</emphasis> RTAS call write operation returns after
                the operation has been enqueued by the firmware but prior to completion
                by the hardware (therefore the operation status is truly not known), the 
                <emphasis>ibm,exti2c</emphasis> RTAS call can return a 
                <emphasis>Status</emphasis> of 0 (success) with the buffer
                unmodified.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> The Buffer format for a read
                operation, if supported, must be as defined in 
                <xref linkend="dbdoclet.50569332_76635" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76635">
                  <title>EXTI2C Buffer Read Operation Format (Optional)</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">Condition</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Byte #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Content</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="3">
                          <para>On Call</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>0x80</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                        <entry>
                          <para>Address of I2C resource</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Length of op. (1-255 with 0 specifying 256)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5...</para>
                        </entry>
                        <entry>
                          <para>Data</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="3">
                          <para>On Return - I2C OK</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>0x80</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                        <entry>
                          <para>Address of I2C resource</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Length of op. (1-255 with 0 specifying 256)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>5...</para>
                        </entry>
                        <entry>
                          <para>Data</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="2">
                          <para>On Return - I2C error</para>
                        </entry>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>0x81</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1-3</para>
                        </entry>
                        <entry>
                          <para>Address of I2C resource</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>I2C operation error code</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> If read operations are not
                supported and a read operation is attempted, then the platform must
                return a 
                <emphasis>Status</emphasis> of -3.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> The maximum total Extended
                Delay imposed by the
                <emphasis>ibm,exti2c</emphasis> command for a single 
                I<superscript>2</superscript>C operation must be less than 2 seconds.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_19739" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EXTI2C option:</emphasis> When the 
                <emphasis>ibm,exti2c</emphasis> RTAS call returns an EXTI2C buffer
                containing an I<superscript>2</superscript>C operation error code, the RTAS 
                <emphasis>Status</emphasis> code must be 0 (success).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Firmware and Software Implementation Note:</emphasis> When the 
        <emphasis>ibm,exti2c</emphasis> RTAS call returns after the operation has
        been enqueued by the firmware but prior to completion by the hardware
        (therefore the operation status is truly not known), the 
        <emphasis>ibm,exti2c</emphasis> RTAS call can return a 
        <emphasis>Status</emphasis> of 0 (success) with the buffer
        unmodified.</para>
      </section>

    </section>
    
    <section>
      <title>PowerPC External Interrupt Option</title>
      <para>The RTAS calls used to access the facilities of the PowerPC
      External Interrupt option need not be serialized by the calling OS. Other
      RTAS rules such as being called in real mode with interrupts disabled
      still apply.</para>
      <para>
      <emphasis role="bold">Note:</emphasis> These RTAS calls make the PowerPC External
      Interrupt option Logical Partition (LPAR) ready.</para>
      
      <section xml:id="dbdoclet.50569332_48295">
        <title><emphasis>ibm,get-xive</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> RTAS must
                implement an 
                <emphasis>ibm,get-xive</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_27983" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,get-xive</emphasis> call must be reentrant to the number of
                processors on the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,get-xive</emphasis> argument call buffer for each
                simultaneous call must be physically unique.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The
                <emphasis>ibm,get-xive</emphasis> call must return the current values of
                the server number and priority fields, as set by the last
                <emphasis>ibm,set-xive</emphasis> call (priority initialized to least
                favored level by firmware at boot), of the External Interrupt Vector
                Entry associated with the interrupt number provided as an input argument
                unless prevented by Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,get-xive</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an unimplemented
                Interrupt # (not reported via an 
                <emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis> property).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_48295" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option combined with the
                Platform Reserved Interrupt Priority Level option:</emphasis> The 
                <emphasis>ibm,get-xive</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an platform
                reserved interrupt priority (reported via an the 
                <emphasis role="bold"><literal>
                &#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis> property).</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_27983">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,get-xive</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,get-xive</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>3</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Interrupt #</para>
                        </entry>
                        <entry>
                          <para>From 
                          <emphasis role="bold"><literal>
                          &#8220;interrupt-ranges&#8221;</literal></emphasis> property</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="2">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-1: Hardware Error</para>
                          <para>-3: Argument Error (Optional)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Server #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0x0 - 2
                          <emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis>
                          </para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Priority</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0x0 - 0xff</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_13631">
        <title><emphasis>ibm,set-xive</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> RTAS must
                implement an 
                <emphasis>ibm,set-xive</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_93043" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,set-xive</emphasis> call must be reentrant to the number of
                processors on the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,set-xive</emphasis> argument call buffer for each
                simultaneous call must be physically unique.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,set-xive</emphasis> call must set values of the server
                number and priority fields of the External Interrupt Vector Entry (XIVE)
                and/or firmware saved priority value (if the interrupt source controller
                does not use an interrupt Enable Register and the interrupt source is
                masked off, either due to a previous
                <emphasis>ibm,int-off</emphasis> call or because the interrupt source was
                never enabled with an 
                <emphasis>ibm,int-on</emphasis> call since boot), associated with the
                interrupt number provided as an input argument unless prevented by
                Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,set-xive</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an unimplemented
                Interrupt number.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_13631" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>
                <emphasis role="bold">For the PowerPC External Interrupt plus the Platform Reserved
                Interrupt Priority Level option:</emphasis> The 
                <emphasis>ibm,set-xive</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an reserved
                Priority value (as reported via an 
                <emphasis role="bold"><literal>
                &#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis> property).</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_93043">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,set-xive</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,set-xive</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>Interrupt #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Interrupt number from appropriate OF device tree
                          property</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Server #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0x00 - 2
                          <emphasis role="bold"><literal>
                          &#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Priority</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0x00 - 0xFF</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 Argument Error (Optional)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_95487">
        <title><emphasis>ibm,int-off</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> RTAS must
                implement an 
                <emphasis>ibm,int-off</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_28484" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-off</emphasis> call must be reentrant to the number of
                processors on the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-off</emphasis> argument call buffer for each
                simultaneous call must be physically unique.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-off</emphasis> call must disable interrupts from the
                interrupt source associated with the interrupt number provided as an
                input argument unless prevented by Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> If the
                interrupt source controller uses an Interrupt Enable Register, the 
                <emphasis>ibm,int-off</emphasis> call must reset the mask bit associated
                with the specified interrupt number; or if the interrupt source
                controller does not use an interrupt Enable Register, the 
                <emphasis>ibm,int-off</emphasis> call must save the priority value of the
                XIVE for later restoration by the 
                <emphasis>ibm,int-on</emphasis> call, or presentation by the 
                <emphasis>ibm,get-xive</emphasis> call and set the priority value of the
                XIVE to the least favored priority value (0xFF), unless prevented by
                Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_95487" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-off</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an unimplemented
                Interrupt number.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28484">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,int-off</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,int-off</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>Interrupt #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Interrupt number from appropriate OF device tree
                          property</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 Argument Error (Optional)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_61000">
        <title><emphasis>ibm,int-on</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> RTAS must
                implement an 
                <emphasis>ibm,int-on</emphasis> call using the argument call buffer
                defined by 
                <xref linkend="dbdoclet.50569332_91226" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-on</emphasis> call must be reentrant to the number of
                processors on the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-on</emphasis> argument call buffer for each simultaneous
                call must be physically unique.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-on</emphasis> call must enable interrupts from the
                interrupt source associated with the interrupt number provided as an
                input argument unless prevented by Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> If the
                interrupt source controller uses an Interrupt Enable Register, the
                <emphasis>ibm,int-on</emphasis> call must set the mask bit associated with
                the specified interrupt number; or if the interrupt source controller
                does not use an interrupt Enable Register, the 
                <emphasis>ibm,int-on</emphasis> call must restore the XIVE priority value
                saved by the previous 
                <emphasis>ibm,int-off</emphasis> call (initialized by the firmware to the
                least favored level at boot) unless prevented by Requirement 
                <xref linkend="LoPAR.Virtualization" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61000" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PowerPC External Interrupt option:</emphasis> The 
                <emphasis>ibm,int-on</emphasis> call must return the 
                <emphasis>Status</emphasis> of -3 (Argument Error) for an unimplemented
                Interrupt number.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_91226">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,int-on</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,int-on</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>Interrupt #</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Interrupt number from appropriate OF device tree
                          property</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 Argument Error (Optional)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_61719">
        <title>MSI Support</title>
        <para>This section describes the RTAS calls required when the MSI option
        is implemented. See 
        <xref linkend="LoPAR.Platform" /> for other platform requirements
        for the MSI option.</para>
        <para>The Message Signaled Interrupt (MSI) and Enhanced MSI (MSI-X)
        capability of PCI IOAs in many cases allows for greater flexibility in
        assignment of external interrupts to IOAs than the predecessor Level
        Sensitive Interrupt (LSI) capability, and in some cases allows the
        treatment of MSIs
        <footnote xml:id="pgfId-1238181">
          <para>This architecture will refer generically to the MSI and MSI-X
          capabilities as simply &#8220;MSI,&#8221; except where differentiation
          is required.</para>
        </footnote>as a resource pool that is reassigned based on availability of
        MSIs and the need of an IOA function for more interrupts than initially
        assigned. Platforms that implement the MSI option implement the 
        <emphasis>ibm,change-msi</emphasis> and 
        <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls.</para>
      
        <section xml:id="dbdoclet.50569332_16274">
          <title><emphasis>ibm,change-msi</emphasis></title>
          <para>The OS uses the 
          <emphasis>ibm,change-msi</emphasis> RTAS call to query the initial number
          of MSIs assigned to a PCI configuration address (that is, to an IOA
          function) and to request a change in the number of MSIs assigned, when
          the platform allows for dynamic reassignment of MSIs for the IOA
          function. The 
          <emphasis>ibm,change-msi</emphasis> RTAS call allows the caller to allow
          the platform to select MSI or MSI-X, to specifically select MSI or MSI-X
          or, if LSIs are allocated by the firmware for the IOA function, to change
          to LSI (by removal of the MSIs assigned). The interrupt source numbers
          assigned to an IOA function are queried via the 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call. The 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is called
          iteratively, once for each interrupt assigned to the IOA function. The
          interrupt source numbers returned by the 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call are the
          numbers used to control the interrupt as in the 
          <emphasis>ibm,get-xive</emphasis>, 
          <emphasis>ibm,set-xive</emphasis>, 
          <emphasis>ibm,int-on</emphasis>, and
          <emphasis>ibm,int-off</emphasis> RTAS calls.</para>
          <para>If a device driver is willing to live with the platform-assigned
          initial number of MSIs, then the device driver does not need to use the 
          <emphasis>ibm,change-msi</emphasis> RTAS call, and can instead use the 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call to
          determine the number of interrupts assigned to each IOA function.</para>
          <para>An OS may abandon the effort to change the MSIs for a given
          configuration address after the first call to 
          <emphasis>ibm,change-msi</emphasis> and prior to a call which gets a
          status back indicating completion, by calling again with the same PCI
          configuration address but with a 
          <emphasis>Function</emphasis> number of 2 (set to default number of
          interrupts) and a 
          <emphasis>Sequence Number</emphasis> of 1. RTAS never returns a 
          <emphasis>Status</emphasis> of -2 or 990x when the call is made with a 
          <emphasis>Function</emphasis> number of 2.</para>
          <para>If an OS successfully changes the number of interrupts, then it
          should consider removing the increase when it deconfigures the IOA
          function, especially if it starts with zero and wants to be backward
          compatible with older device drivers that may not understand MSIs. To
          remove all MSIs, set the Requested Number of Interrupts to zero. But it
          should be noted, that once set to zero, there is no guarantee that on a
          future request there will be any MSIs available to assign from the pool.
          Adding MSIs to an IOA function which has LSIs assigned disables those
          LSIs but does not remove them, and then removing the MSIs that replaced
          the LSIs re-uses the same (previously removed) LSIs (mapped to the same
          LSI source numbers as the previous LSI source numbers).</para>
          <para>The presence of the 
          <emphasis role="bold"><literal>&#8220;ibm,change-msix-capable&#8221;</literal></emphasis> property
          specifies that the platform implements the version of this RTAS call that
          allows 
          <emphasis>Number Outputs</emphasis> equal to 4 and 
          <emphasis>Functions</emphasis> 3, 4 and 5.</para>
          <para>If the 
          <emphasis>ibm,change-msi</emphasis> RTAS call is made with 
          <emphasis>Number Outputs</emphasis> equal to 4 or with 
          <emphasis>Function</emphasis> equal to 3 or 4 when the 
          <emphasis role="bold"><literal>&#8220;ibm,change-msix-capable&#8221;</literal></emphasis> property does
          not exist in the 
          <emphasis role="bold"><literal>/rtas</literal></emphasis> node, then the call will return a 
          <emphasis>Status</emphasis> of -3 (Invalid Parameter). Specifying 
          <emphasis>Function</emphasis> 3 (MSI) also disables MSI-X for the
          specified IOA function, and likewise specifying 
          <emphasis>Function</emphasis> 4 (MSI-X) disables MSI for the IOA function.
          It is unnecessary to specify a 
          <emphasis>Requested Number of Interrupts</emphasis> of zero when switching
          between MSI and MSI-X. Specifying the 
          <emphasis>Requested Number of Interrupts</emphasis> to zero for either 
          <emphasis>Function</emphasis> 3 or 4 removes all MSI &amp; MSI-X
          interrupts from the IOA function. It is permissible to use LSI, MSI and
          MSI-X on different IOA functions.</para>
          <para>The default (initial) assignment of interrupts is defined in 
          <xref linkend="LoPAR.Platform" />.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The platform must implement the 
                  <emphasis>ibm,change-msi</emphasis> call using the argument call buffer
                  defined by 
                  <xref linkend="dbdoclet.50569332_69854" />.</para>
            
                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_69854">
                    <title><emphasis>ibm,change-msi</emphasis> Argument Call Buffer</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="8">
                            <para>In</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Token</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Token for 
                            <emphasis>ibm,change-msi.</emphasis></para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number Inputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>6</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Number Outputs</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>3 or 4, when the 
                            <emphasis role="bold"><literal>
                            &#8220;ibm,change-msix-capable&#8221;</literal></emphasis> property is
                            present, 3 otherwise.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Config_addr</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Configuration Space Address (Register field 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>
                              <emphasis>Function</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Determines action of this call:</para>
                            <para>0: Query only (only return actual number of MSI or MSI-X
                            interrupts assigned to the PCI configuration address).</para>
                            <para>1: If 
                            <emphasis>Number Outputs</emphasis> is equal to 3, request to
                            set to a new number of MSIs (including set to 0).</para>
                            <para>If the 
                            <emphasis role="bold"><literal>
                            &#8220;ibm,change-msix-capable&#8221;</literal></emphasis> property exists
                            and 
                            <emphasis>Number Outputs</emphasis> is equal to 4, request is to
                            set to a new number of MSI or MSI-X (platform choice)
                            interrupts (including set to 0).</para>
                            <para>2: Request to set back to the default number of
                            interrupts (also aborts a change in progress; that is, one that
                            has previously returned a 
                            <emphasis>Status</emphasis> of -2 or 990x)</para>
                            <para>3: (Only valid if 
                            <emphasis role="bold"><literal>
                            &#8220;ibm,change-msix-capable&#8221;</literal></emphasis> exists):
                            Request to set to a new number of MSIs (including set to
                            0)</para>
                            <para>4: (Only valid if 
                            <emphasis role="bold"><literal>
                            &#8220;ibm,change-msix-capable&#8221;</literal></emphasis> exists):
                            Request to set to a new number of MSI-X interrupts (including
                            set to 0)</para>
                            <para>5: (Only valid if
                            <emphasis role="bold"><literal>
                            &#8220;ibm,change-msix-capable&#8221;</literal></emphasis> exists):
                            Request to set to a new number of 32 bit MSI (including set to 0) 
                            disregarding the adapter capability to support 64 bit MSI.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Requested Number of Interrupts</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>The total number of MSIs being requested for the PCI
                            configuration address. A value of 0 is specified in order to
                            remove all MSIs for the PCI configuration address. This input
                            parameter is ignored by RTAS for 
                            <emphasis>Function</emphasis> values other than 1, 3, 4 or 5.</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="3">
                            <para>Out</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Status</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>-3: Parameter error</para>
                            <para>-2: Call again</para>
                            <para>-1: Hardware error</para>
                            <para>0: Success</para>
                            <para>990x: Extended Delay</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Final Number of Interrupts</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Number of interrupts assigned to the PCI configuration
                            address at the successful completion of this call (
                            <emphasis>Status</emphasis> of 0). For 
                            <emphasis>Function</emphasis> 1, 3, or 4, if a greater number
                            was requested than what was previously assigned, the final
                            number may be less than what was requested, even though a 
                            <emphasis>Status</emphasis> of 0 is returned.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Next Sequence Number</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Integer to be returned as the 
                            <emphasis>Sequence Number</emphasis> parameter on the next call.
                            This output is only valid if a 
                            <emphasis>Status</emphasis> of -2 or 990x is returned.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Type of Interrupts</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>This field is only valid when the 
                            <emphasis>Final Number of Interrupts</emphasis> is
                            non-zero.</para>
                            <para>1: MSI</para>
                            <para>2: MSI-X</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The 
                  <emphasis>Final number of Interrupts</emphasis> and 
                  <emphasis>Type of Interrupts</emphasis> must be valid when the platform
                  returns a 
                  <emphasis>Status</emphasis> of 0 (Success), regardless of whether the
                  original number and final number of interrupts assigned is different and
                  regardless of whether or not the platform allows MSI resources to be
                  reassigned for the specified PCI configuration address.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The platform must return a 
                  <emphasis>Status</emphasis> of -3 (Parameter error) from 
                  <emphasis>ibm,change-msi</emphasis>, with no change in interrupt
                  assignments if the PCI configuration address does not support MSI and 
                  <emphasis>Function</emphasis> 3 was requested (that is, the 
                  <emphasis role="bold"><literal>&#8220;ibm,req#msi&#8221;</literal></emphasis> property must exist for the
                  PCI configuration address in order to use 
                  <emphasis>Function</emphasis> 3), or does not support MSI-X and 
                  <emphasis>Function</emphasis> 4 is requested (that is, the 
                  <emphasis role="bold"><literal>&#8220;ibm,req#msi-x&#8221;</literal></emphasis> property must exist for
                  the PCI configuration address in order to use 
                  <emphasis>Function</emphasis> 4), or if neither MSIs nor MSI-Xs are
                  supported and 
                  <emphasis>Function</emphasis> 1 is requested.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> If there are zero MSIs assigned
                  to the target IOA function but there is one or more LSIs assigned, then a
                  call to 
                  <emphasis>ibm,change-msi</emphasis> which successfully changes the number
                  of MSIs assigned to non-zero must also disable the LSIs in the IOA
                  function&#8217;s configuration space and must keep the LSI platform
                  resources available to the IOA function in the case the MSIs are removed
                  (see Requirement 
                  <xref linkend="dbdoclet.50569332_88831" />).</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry xml:id="dbdoclet.50569332_88831">
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis>
                  If there are a
                  non-zero number of MSIs assigned to the target IOA function and if that
                  IOA function originally had some LSIs assigned, then a call to 
                  <emphasis>ibm,change-msi</emphasis> which successfully changes the number
                  of MSIs assigned to zero must also reassign any LSIs that were originally
                  assigned to that IOA function, using the same interrupt number that was
                  originally assigned (that is, the platform must reserve an originally
                  assigned LSI for a IOA function in case it needs to reassign it), and
                  must enable the LSIs in the IOA function&#8217;s configuration
                  space.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> If the platform supports the
                  changing of MSIs, then it must support the reduction in the number of
                  interrupts by the 
                  <emphasis>ibm,change-msi</emphasis> call, including setting the number of
                  MSIs to 0.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> On the first call of 
                  <emphasis>ibm,change-msi</emphasis>, the 
                  <emphasis>Sequence Number</emphasis> must be a 1.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> If 
                  <emphasis>ibm,change-msi</emphasis> returns a 
                  <emphasis>Status</emphasis> of -2 (Call again) or 990x (Extended Delay),
                  then the caller must provide on the next call to 
                  <emphasis>ibm,change-msi</emphasis>, one of the following:</para>
                  
                  <itemizedlist>		      
                    <listitem>
                      <para>All input parameters the same as the initial call except with the  
                      <emphasis>Sequence Number</emphasis> set to the value in 
                      <emphasis>Next Sequence Number</emphasis> returned from the previous 
                      <emphasis>ibm,change-msi</emphasis> call.</para>
                    </listitem>
                    
                    <listitem>
                      <para>All input parameters the same as the initial call except with 
                      <emphasis>Function</emphasis> set to 2 and the 
                      <emphasis>Sequence Number</emphasis> set to 1, if the caller is wanting to
                      abort the previously started 
                      <emphasis>ibm,change-msi</emphasis> operation.</para>
                    </listitem>
                  </itemizedlist>		      
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> If the 
                  <emphasis>ibm,change-msi</emphasis> RTAS call returns something other than
                  0 for the 
                  <emphasis>Final Number of Interrupts</emphasis>, then the 
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call must be
                  used to get the current interrupt source numbers, even if the 
                  <emphasis>ibm,change-msi</emphasis> call has returned the same number of
                  interrupts as before the call.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> Firmware must not return a 
                  <emphasis>Status</emphasis> of -2 or 990x when the 
                  <emphasis>Requested Number of Interrupts</emphasis> is set to 0 or for 
                  <emphasis>Function</emphasis> 0 (query only) or for 
                  <emphasis>Function</emphasis> 2 (set back to default number).</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> When the 
                  <emphasis>set-indicator</emphasis> RTAS call is made to isolate an IOA
                  (for both DLPAR and PCI Hot Plug operations), the platform must release
                  any additional MSI numbers that were obtained through the 
                  <emphasis>ibm,change-msi</emphasis> RTAS call and make them available for
                  use by other
                  <emphasis>ibm,change-msi</emphasis> calls.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> An OS or device driver that is
                  calling 
                  <emphasis>ibm,change-msi</emphasis> for the purpose of changing the number
                  or type of interrupts for the IOA function must assure that the IOA
                  function cannot be actively performing operations that will generate
                  interrupts during the process of changing the number or type of
                  interrupts.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16274" 
              xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The platform must restore the
                  IOA&#8217;s MSI configuration space after a reset operation which occurs
                  following boot, to what it was previous to the reset operation, and
                  provide the same MSI assignments through the reset operation, unless a DR
                  isolate/unisolate operation has been performed (in which case the IOA's
                  MSI configuration space is set as it would at boot time).</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para>
            <emphasis role="bold">Software Implementation Notes:</emphasis>
          </para>
          
          <orderedlist>		      
            <listitem>
              <para>Interrupt source numbers for MSIs are not necessarily be
              assigned contiguously.</para>
           </listitem>
    
            <listitem>
              <para>MSIs and MSI source numbers are not shared (see Requirement 
              <xref linkend="LoPAR.Platform" />).</para>
            </listitem>
    
            <listitem>
              <para>For a multi-function IOA, the 
              <emphasis>ibm,change-msi</emphasis> call is called for each function for
              which the number of MSIs is to be changed.</para>
            </listitem>
    
            <listitem>
              <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,change-msi</emphasis> again. However, software may issue the
              
              <emphasis>ibm,change-msi</emphasis> call again either earlier or later
              than this.</para>
            </listitem>
    
            <listitem>
              <para>During a sequence of calls which return -2 or 990x, software may
              abort at any time by setting the 
              <emphasis>Function</emphasis> equal to 2 and the 
              <emphasis>Sequence Number</emphasis> to 1.</para>
            </listitem>
    
            <listitem>
              <para>When there is a non-zero number of MSI or MSI-X interrupts
              assigned, and when software attempts to change the type of interrupts
              (MSI to MSI-X interrupt or MSI-X to MSI) at the same time as changing the
              number of interrupts, the platform may return the same number of
              interrupts as previously assigned, even though a greater number is
              available. In this case a second call to 
              <emphasis>ibm,change-msi</emphasis> to increase the number of interrupts
              may produce a greater number of interrupts.</para>
            </listitem>
    
            <listitem>
              <para>The platform will return a status -2 or 990x only when the OS 
              indicates support. The OS indicates support via ibm,client-architecture-support, 
              vector 4. See <xref linkend="LoPAR.DeviceTree" /> section on "Root Node Methods" 
              for more information.</para>
            </listitem>
          </orderedlist>		      
          
        </section>
        
        <section xml:id="sec_query_int_src_num">
          <title><emphasis>ibm,query-interrupt-source-number</emphasis></title>
          <para>The 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is used
          to query the interrupt source number and type (level sensitive for LSIs,
          edge triggered for MSIs) for a specific PCI IOA function&#8217;s
          interrupt, if one exists. That is, for a given PCI configuration address
          (
          <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low,</emphasis> and
          <emphasis>config_addr</emphasis>) and function interrupt number. This
          call is issued once for each interrupt of each IOA function, in order to
          obtain the interrupt source number and type for that interrupt. For
          example, if the 
          <emphasis>ibm,change-msi</emphasis> RTAS call has previously returned a
          value of &#8220;n&#8221; interrupts for the IOA function, then the call
          is made &#8220;n&#8221; times for that function (with a relative
          interrupt number of 0 to n-1).</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_query_int_src_num" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The platform must implement the 
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call using the
                  argument call buffer defined by 
                  <xref linkend="dbdoclet.50569332_13934" />
                  <emphasis>.</emphasis></para>
                  <para>
                  &#160;</para>
                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_13934">
                    <title>Argument Call Buffer 
                    <emphasis>ibm,query-interrupt-source-number</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">
                            <para>In</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Token</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Token for 
                            <emphasis>ibm,query-interrupt-source-number</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>Config_addr</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>Configuration Space Address (Register field 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>
                              <emphasis>IOA Function Interrupt Number</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>The relative number of the interrupt within the PCI
                            configuration address, with a value of 0 being the first
                            interrupt of the PCI configuration address.</para>
                          </entry>
                        </row>
                        <row>
                          <entry morerows="2">
                            <para>Out</para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis>Status</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>-3: Parameter error</para>
                            <para>-1: Hardware error</para>
                            <para>0: Success</para>
                            <para>1: No interrupt assigned for the given PCI configuration
                            address and 
                            <emphasis>IOA Function Interrupt Number.</emphasis></para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Interrupt Source Number</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>The interrupt source number corresponding to the PCI
                            configuration address and 
                            <emphasis>IOA Function Interrupt Number</emphasis>, when a 
                            <emphasis>Status</emphasis> of 0 is returned. Undefined for
                            other 
                            <emphasis>Status</emphasis> values
                            <emphasis>.</emphasis></para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>
                              <emphasis>Interrupt Source Trigger</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>The interrupt source trigger corresponding to the PCI
                            configuration address and 
                            <emphasis>IOA Function Interrupt Number</emphasis>, when a 
                            <emphasis>Status</emphasis> of 0 is returned. Undefined for
                            other 
                            <emphasis>Status</emphasis> values
                            <emphasis>.</emphasis></para>
                            <para>0: Level sensitive</para>
                            <para>1: Edge triggered</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_query_int_src_num" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The interrupt source numbers
                  returned by the 
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call must be
                  the numbers used to control the interrupt as in the 
                  <emphasis>ibm,get-xive</emphasis>, 
                  <emphasis>ibm,set-xive</emphasis>, 
                  <emphasis>ibm,int-on</emphasis>, and 
                  <emphasis>ibm,int-off</emphasis> RTAS calls.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_query_int_src_num" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the MSI option:</emphasis> The 
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call must
                  return a 
                  <emphasis>Status</emphasis> of 1 (no interrupt assigned) if the inputs
                  specify a valid PCI configuration address and the PCI configuration
                  address does not have an interrupt assigned for the specified 
                  <emphasis>IOA Function Interrupt Number.</emphasis></para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
          <para>
          <emphasis role="bold">Software and Firmware Implementation Note:</emphasis> Software
          may use the 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call for all 
          <emphasis>IOA Function Interrupt Number</emphasis> values starting at 0
          until a 
          <emphasis>Status</emphasis> of 1 is returned, rather than using 
          <emphasis>ibm,change-msi Function</emphasis> 0 (query). That is, the 
          <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call works
          even when the 
          <emphasis role="bold"><literal>&#8220;ibm,req#msi&#8221;</literal></emphasis> property does not exist for
          the IOA (that is even when the IOA is not requesting one or more MSIs),
          This might be desirable, for example, if software never plans on using
          the capability to change the number of MSIs, and therefore does not have
          any other use for the 
          <emphasis>ibm,change-msi</emphasis> call.</para>
        </section>

      </section>

    </section>
    
    <section xml:id="dbdoclet.50569332_39444">
      <title>Enhanced I/O Error Handling (EEH) Option Functions</title>
      <para>The EEH option requires several additional RTAS calls. In addition,
      the Error Injection option RTAS calls are required to be implemented, in
      order to be able to test device driver code that implements recovery
      based on the EEH option.</para>
      <para>See also, 
      <xref linkend="LoPAR.Platform" />, for additional information
      about implementing EEH error recovery.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis> The IOA bus error injection
              function of the Error Injection option RTAS call must be implemented
              concurrently with the EEH option (that is, the 
              <emphasis>ioa-bus-error</emphasis> token must exist in the 
              <emphasis role="bold"><literal>&#8220;ibm,errinjct-tokens&#8221;</literal></emphasis> property).</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis> If the EEH option is implemented
              for the specified PE configuration address, then calls to the
              
              <emphasis>ibm,set-eeh-option, ibm,set-slot-reset,</emphasis> and 
              <emphasis>ibm,slot-error-detail</emphasis> RTAS calls must be governed by 
              <xref linkend="dbdoclet.50569332_19683" />, otherwise if one of the
              invalid transitions in 
              <xref linkend="dbdoclet.50569332_19683" /> is attempted, then return a 
              <emphasis>Status</emphasis> as defined by 
              <xref linkend="dbdoclet.50569332_49282" />.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para>If the EEH option is not implemented for
              the specified PE configuration address and a call is made to one of the 
              <emphasis>ibm,set-eeh-option, ibm,set-slot-reset,</emphasis> or 
              <emphasis>ibm,slot-error-detail</emphasis> RTAS calls, then return a 
              <emphasis>Status</emphasis> of -3 (parameter error).</para>
              <para>
              <emphasis role="bold">Software Implementation Note:</emphasis> Some transitions in 
              <xref linkend="dbdoclet.50569332_19683" /> are made asynchronously to the
              OS by the platform (in exceptional cases; see table for details). If
              software receives a 
              <emphasis>Status</emphasis> of -7 (Unexpected state change) on an RTAS
              call which is attempting to change state in 
              <xref linkend="dbdoclet.50569332_19683" />, then software should read the
              state again via the 
              <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call, in order to
              obtain the current state. Some legacy implementations may return a -1
              instead of a -7.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_35100">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis>
              If the platform
              activates the reset to a PE (for example, as part of a recovery action
              above the PE), including the case where the platform has temporarily
              deactivated and then reactivated the reset, then the platform must hide
              such PE state transition(s) from the OS by returning a 
              <emphasis>Status</emphasis> of 5 (PE is unavailable) with 
              <emphasis>PE Unavailable Info</emphasis> indicating a non-zero value
              (temporarily unavailable) for the 
              <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call, until which
              time the required minimum reset active hold time for the hardware within
              the PE has been met.</para>
              <para>
              <emphasis role="bold">Software Implementation Note:</emphasis> Relative to the
              platform automatically resetting the PE as part of error recovery, as
              mentioned in Requirement 
              <xref linkend="dbdoclet.50569332_35100" />, the 
              <emphasis>PE Recovery Info</emphasis> output of the 
              <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call is provided to
              enable the software to determine that such a reset has occurred.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_10576">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis>
              If the platform
              deactivates the reset to a PE, except in the case where the OS has
              instructed it to do so with the 
              <emphasis>ibm,set-slot-reset Function</emphasis> 0, then the platform must
              do all the following:</para>
              
              <orderedlist numeration="loweralpha">		      
                <listitem>
                  <para>Hide such a deactivation from the OS during the time that the PE
                  reset is deactivated by returning a 
                  <emphasis>Status</emphasis> of 5 (PE is unavailable) with 
                  <emphasis>PE Unavailable Info</emphasis> indicating a non-zero value
                  (temporarily unavailable) for the 
                  <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call.</para>
                </listitem>
        
                <listitem>
                  <para>Force OS MMIO accesses to the PE during the deactivation time to
                  look like the PE is reset.</para>
                </listitem>
        
                <listitem>
                  <para>Prevent the PE from introducing errors into the system (for
                  example, from DMA or due to the reset being deactivated prior to the
                  proper active hold time).</para>
                </listitem>
        
                <listitem>
                  <para>Reactivate the reset, hiding the reset active hold time as
                  required by Requirement 
                  <xref linkend="dbdoclet.50569332_35100" />, or force the PE into the
                  permanently unavailable state (return a 
                  <emphasis>Status</emphasis> of 5 (PE is unavailable) with 
                  <emphasis>PE Unavailable Info</emphasis> indicating a zero value for the 
                  <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call).</para>
                </listitem>
              </orderedlist>		      
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis> The Bridged-I/O EEH option must
              be implemented concurrently with the EEH option.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis> The 64 bit IOA bus error
              injection function of the Error Injection option RTAS call must be
              implemented concurrently with the EEH option (that is, the 
              <emphasis>ioa-bus-error-64</emphasis> token must exist in the 
              <emphasis role="bold"><literal>&#8220;ibm,errinjct-tokens&#8221;</literal></emphasis> property).</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39444" 
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the EEH option:</emphasis> The platform must implement the 
              <emphasis>ibm,configure-pe</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_19683">
        <title>PE State Transition Table</title>
        <tgroup cols="7" align="center">
          <colspec colname="c1" colwidth="14*" />
          <colspec colname="c2" colwidth="14*" />
          <colspec colname="c3" colwidth="14*" />
          <colspec colname="c4" colwidth="14*" />
          <colspec colname="c5" colwidth="14*" />
          <colspec colname="c6" colwidth="14*" />
          <colspec colname="c7" colwidth="14*" />
          <thead valign="middle">
            <row>
              <entry morerows="1">
                <para>
                  <emphasis role="bold">
                    <emphasis>Initial PE State
                    <footnote xml:id="pgfId-1169335">
                      <para>The state as would be returned from 
                      <emphasis>ibm,read-slot-reset-state2</emphasis>, when no
                      asynchronous platform transition has occurred.</para>
                    </footnote></emphasis>
                  </emphasis>
                </para>
              </entry>
              <entry nameend="c7" namest="c2" align="center">
                <para>
                  <emphasis role="bold">
                    <emphasis>Final PE State</emphasis>
                    <emphasis>
                      <footnoteref linkend="pgfId-1169335" />
                    </emphasis>
                  </emphasis>
                </para>
              </entry>
            </row>
            <row>
              <entry align="center">
                <para>0</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnote xml:id="dbdoclet.50569332_61717">
                    <para><emphasis>Load</emphasis>/<emphasis> Store</emphasis> allowed means 
                    the <emphasis> Loads</emphasis> or <emphasis> Stores</emphasis> channel is 
                    open to the PE, and not necessarily that the PE itself has its MMIO space 
                    enabled. The components within the PE also contain enable/disable bits 
                    (for example, the PCI configuration space Memory Space and IO Space 
                    enable bits in the PCI header Device Control register).</para>
                  </footnote>
                </para>
                <para>DMA Allowed
                  <footnote xml:id="dbdoclet.50569332_68778">
                    <para>DMA allowed means the DMA channel is open to the PE, if the PE 
                    itself has its DMA enabled. The components within the PE also contain 
                    enable/disable bits (for example, the PCI configuration space Bus Master 
                    enable bit in the PCI header Device Control register).</para>
                  </footnote>
                </para>
                <para>(Normal Operations)</para>
              </entry>
              
              <entry align="center">
                <para>1</para>
                <para>Reset
                  <footnote>
                    <para>Reset may mean that the PE is being held in the reset state by 
                    a reset signal or Hot Reset (PCI Express), or that it may have been 
                    put into this state by the platform via a PCI Express Function Level 
                    Reset (FLR) in response to the <emphasis> ibm,set-slot-reset</emphasis> 
                    RTAS call. In the case of FLR, the platform makes the pulse of the FLR 
                    look like the Hot Reset case to the OS in terms of the Reset state 
                    (See <xref linkend="dbdoclet.50569332_86249"/> for more information). 
                    Note that the platform does not monitor writes to the FLR bit of an 
                    IOA, and so OS or Device Driver writes directly to the FLR bit on an 
                    IOA will not affect the PE State as shown in 
                    <xref linkend="dbdoclet.50569332_19683"/>.</para>
                  </footnote>
                </para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled
                  <footnote xml:id="dbdoclet.50569332_77498">
                    <para><emphasis> Load</emphasis>/<emphasis> Store</emphasis> disabled 
                    means that either the PE is in the MMIO Stopped state or that the PE 
                    is reset, the latter giving the appearance of being MMIO Stopped.</para>
                  </footnote>
                </para>
                <para>DMA Disabled
                  <footnote xml:id="dbdoclet.50569332_86352">
                    <para>DMA disabled means that either the PE is in the DMA
                    Stopped state or that the PE is reset, the latter giving 
                    the appearance of being DMA Stopped.</para>
                  </footnote>
                </para>
              </entry>

              <entry align="center">
                <para>2</para>
                <para>Not Reset
                  <footnote>
                    <para>Although the current state is &#8220;Not Reset&#8221;, 
                    the PE may have been reset by the platform in the process of 
                    getting to this state. The <emphasis> PE Recovery Info</emphasis> 
                    output of the <emphasis> ibm,read-slot-reset-state2</emphasis> 
                    RTAS call will indicate if the platform has done such a reset.</para>
                  </footnote>
                </para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled
                  <footnote>
                    <para>In the MMIO Stopped state.</para>
                  </footnote>
                </para>
                <para>DMA Disabled
                  <footnote xml:id="dbdoclet.50569332_15974">
                    <para>In the DMA Stopped state.</para>
                  </footnote>
                </para>
              </entry>
              
              <entry align="center">
                <para>4</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnoteref linkend="dbdoclet.50569332_61717" />
                </para>
                <para>DMA Disabled
                  <footnoteref linkend="dbdoclet.50569332_15974" />
                </para>
              </entry>
              
              <entry align="center">
                <para>5</para>
                <para>Temporarily</para>
                <para>Unavailable
                  <footnote xml:id="dbdoclet.50569332_15646">
                    <para>Temporarily unavailable is signaled by a non-zero value r
                    eturned in the <emphasis>PE Unavailable Info</emphasis> of the 
                    <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS calls.</para>
                  </footnote>
                </para>
              </entry>
              
              <entry align="center">
                <para>5</para>
                <para>Permanently Unavailable
                  <footnote xml:id="dbdoclet.50569332_99978">
                    <para>Permanently unavailable is signaled by a zero value 
                    returned in the <emphasis>PE Unavailable Info</emphasis> 
                    of the <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS calls.</para>
                  </footnote>
                </para>
              </entry>
              
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry align="center">
                <para>0</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnoteref linkend="dbdoclet.50569332_61717" />
                </para>
                <para>DMA Allowed
                  <footnoteref linkend="dbdoclet.50569332_68778"/>
                </para>
                <para>(Normal Operations)</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 1 or 3, or via a hardware
                initiated action
                <footnote xml:id="pgfId-1240216">
                  <para>The hardware would not normally initiate this
                  transition; such implementation would only exist where the
                  platform only implements EEH Stopped State via a reset
                  (always) of the PE (that is, only implements states 0, 1, and
                  5 of this table), which is not applicable for LoPAR
                  Compliant platforms.</para>
                </footnote></para>
              </entry>
              <entry>
                <para>Hardware causes this state transition when EEH is enabled
                and an error occurs or firmware may cause due to higher level
                error recovery action</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Platform initiated action</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,slot-error-detail</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2, or platform detected permanent
                error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>1</para>
                <para>Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled</para>
                <para>DMA Disabled
                  <footnoteref linkend="dbdoclet.50569332_86352"/>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 0
                <footnote xml:id="pgfId-1255997">
                  <para>The platform also removes the PE from the EEH Stopped
                  state, if applicable, on the transition from state 1 to state
                  0.</para>
                </footnote></para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 1 or 3</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Platform initiated action</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,slot-error-detail</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2, or platform detected permanent
                error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>2</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled
                  <footnoteref linkend="dbdoclet.50569332_77498" />
                </para>
                <para>DMA Disabled
                  <footnoteref linkend="dbdoclet.50569332_15974" />
                </para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
                <para>Must go through</para>
                <para>state 4 or state 1</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 1 or 3, or via a hardware
                initiated action
                <emphasis>
                  <footnoteref linkend="pgfId-1240216" />
                </emphasis></para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-eeh-option</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2</para>
              </entry>
              <entry>
                <para>Platform initiated action</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,slot-error-detail</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2, or hardware detected permanent
                error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>4</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnoteref linkend="dbdoclet.50569332_61717" />
                </para>
                <para>DMA Disabled
                  <footnoteref linkend="dbdoclet.50569332_15974" />
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-eeh-option</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 3</para>
                <para>See Requirement</para>
                <para>
                  <xref linkend="dbdoclet.50569332_88517" />
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 1 or 3, or via a hardware
                initiated action
                <emphasis>
                  <footnoteref linkend="pgfId-1240216" />
                </emphasis></para>
              </entry>
              <entry>
                <para>Hardware causes this state transition when EEH is enabled
                and an error occurs or firmware may cause due to higher level
                error recovery action</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>Platform initiated action</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,slot-error-detail</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2, or platform detected permanent
                error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>5</para>
                <para>Temporarily</para>
                <para>Unavailable
                  <footnoteref linkend="dbdoclet.50569332_15646" />
                </para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Platform initiated action</para>
              </entry>
              <entry>
                <para>Platform initiated action
                <footnote xml:id="pgfId-1169527">
                  <para>This transition cannot occur if the PE was in the reset
                  state prior to the platform transition to the temporarily
                  unavailable state. See Requirement <xref linkend="dbdoclet.50569332_10576" />.</para>
                </footnote>.</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>
                  <emphasis>ibm,slot-error-detail</emphasis>
                </para>
                <para>
                <emphasis>Function</emphasis> 2, or platform detected permanent
                error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>5</para>
                <para>Permanently Unavailable
                  <footnoteref linkend="dbdoclet.50569332_99978" />
                </para>
              </entry>
              <entry>
                <para>Power cycle,</para>
                <para>Partition reboot,</para>
                <para>or DLPAR</para>
                <para>re-assignment</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Not a valid</para>
                <para>transition</para>
              </entry>
              <entry>
                <para>Not a valid transition</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
      <xref linkend="dbdoclet.50569332_19683" /> depicts the four main functions
      for controlling a PE&#8217;s state:</para>
      
      <itemizedlist>		      
        <listitem>
          <para><emphasis>ibm,set-eeh-option Function</emphasis> 2 for releasing a PE from
          the MMIO Stopped State, when the PE is in State 2 (MMIO Stopped State and
          DMA Stopped State both active).</para>
        </listitem>
        
        <listitem>
          <para><emphasis>ibm,set-eeh-option Function</emphasis> 3 for releasing a PE from
          the DMA Stopped State, when the PE is in State 3 (MMIO Stopped State not
          active and DMA Stopped State active).</para>
        </listitem>
        
        <listitem>
          <para><emphasis>ibm,set-slot-reset Function</emphasis> 0 for releasing a
          PE&#8217;s reset.</para>
        </listitem>
        
        <listitem>
          <para><emphasis>ibm,set-slot-reset Function</emphasis> 1for activating a
          PE&#8217;s reset.</para>
        </listitem>
      </itemizedlist>		
            
      <para>
      <emphasis role="bold">Implementation Note:</emphasis> In the last two bullets, above,
      for the case of the platform&#8217;s use of FLR for resetting the PE, the
      meaning of &#8220;activating&#8221; and &#8220;deactivating&#8221; the
      PE&#8217;s reset has slightly different meaning, but the platform makes
      the EEH recovery model transparent. See 
      <xref linkend="dbdoclet.50569332_86249" /> for more details.</para>
      <para>
      <xref linkend="dbdoclet.50569332_49282" /> is a summary of the expected
      results of the above four operations. The -7 
      <emphasis>Status</emphasis> returns generally will occur for the cases
      where the PE state has been changed asynchronously to the OS by the
      platform. In these cases, software should read the state again (via the 
      <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call) in order to
      determine the current hardware state.</para>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_49282">
        <title>PE State Control</title>
        <tgroup cols="9" align="center">
          <colspec colname="c1" colwidth="5*" />
          <colspec colname="c2" colwidth="17*" />
          <colspec colname="c3" colwidth="11*" />
          <colspec colname="c4" colwidth="11*" />
          <colspec colname="c5" colwidth="11*" />
          <colspec colname="c6" colwidth="11*" />
          <colspec colname="c7" colwidth="11*" />
          <colspec colname="c8" colwidth="11*" />
          <colspec colname="c9" colwidth="11*" />
          <thead valign="middle">
            <row>
              <entry morerows="1"><?dbfo orientation="90"?><?dbfo rotated-width="1.5in"?>
                <para>RTAS Call</para>
              </entry>
              <entry morerows="1">
                <para>Function</para>
              </entry>
              <entry morerows="1">
                <para>Result and <emphasis>Status</emphasis></para>
              </entry>
              <entry nameend="c9" namest="c4">
                <para>
                  <emphasis role="bold">
                    <emphasis>Initial PE State
                    <footnote xml:id="pgfId-1169354">
                      <para>The state as would be returned from 
                      <emphasis>ibm,read-slot-reset-state2</emphasis>, when no
                      asynchronous platform transition has occurred.</para>
                    </footnote></emphasis>
                  </emphasis>
                </para>
              </entry>
            </row>

            <row>              
              <entry align="center">
                <para>0</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnote xml:id="dbdoclet.50569332_61717_2">
                    <para><emphasis>Load</emphasis>/<emphasis> Store</emphasis> allowed means 
                    the <emphasis> Loads</emphasis> or <emphasis> Stores</emphasis> channel is 
                    open to the PE, and not necessarily that the PE itself has its MMIO space 
                    enabled. The components within the PE also contain enable/disable bits 
                    (for example, the PCI configuration space Memory Space and IO Space 
                    enable bits in the PCI header Device Control register).</para>
                  </footnote>
                </para>
                <para>DMA Allowed
                  <footnote>
                    <para>DMA allowed means the DMA channel is open to the PE, if the PE 
                    itself has its DMA enabled. The components within the PE also contain 
                    enable/disable bits (for example, the PCI configuration space Bus Master 
                    enable bit in the PCI header Device Control register).</para>
                  </footnote>
                </para>
                <para>(Normal Operations)</para>
              </entry>
              
              <entry align="center">
                <para>1</para>
                <para>Reset
                  <footnote>
                    <para>Reset may mean that the PE is being held in the reset state by 
                    a reset signal or Hot Reset (PCI Express), or that it may have been 
                    put into this state by the platform via a PCI Express Function Level 
                    Reset (FLR) in response to the <emphasis> ibm,set-slot-reset</emphasis> 
                    RTAS call. In the case of FLR, the platform makes the pulse of the FLR 
                    look like the Hot Reset case to the OS in terms of the Reset state 
                    (See <xref linkend="dbdoclet.50569332_86249"/> for more information). 
                    Note that the platform does not monitor writes to the FLR bit of an 
                    IOA, and so OS or Device Driver writes directly to the FLR bit on an 
                    IOA will not affect the PE State as shown in 
                    <xref linkend="dbdoclet.50569332_19683"/>.</para>
                  </footnote>
                </para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled
                  <footnote >
                    <para><emphasis> Load</emphasis>/<emphasis> Store</emphasis> disabled 
                    means that either the PE is in the MMIO Stopped state or that the PE 
                    is reset, the latter giving the appearance of being MMIO Stopped.</para>
                  </footnote>
                </para>
                <para>DMA Disabled
                  <footnote>
                    <para>DMA disabled means that either the PE is in the DMA
                    Stopped state or that the PE is reset, the latter giving 
                    the appearance of being DMA Stopped.</para>
                  </footnote>
                </para>
              </entry>

              <entry align="center">
                <para>2</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Disabled
                  <footnote>
                    <para>In the MMIO Stopped state.</para>
                  </footnote>
                </para>
                <para>DMA Disabled</para>
              </entry>
              
              <entry align="center">
                <para>4</para>
                <para>Not Reset</para>
                <para>
                <emphasis>Load</emphasis>/
                <emphasis>Store</emphasis> Allowed
                  <footnoteref linkend="dbdoclet.50569332_61717_2" />
                </para>
                <para>DMA Disabled
                  <footnote>
                    <para>In the DMA Stopped state.</para>
                  </footnote>
                </para>
              </entry>
              
              <entry align="center">
                <para>5</para>
                <para>Temporarily</para>
                <para>Unavailable
                  <footnote>
                    <para>Temporarily unavailable is signaled by a non-zero value 
                    returned in the <emphasis>PE Unavailable Info</emphasis> of the 
                    <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS calls.</para>
                  </footnote>
                </para>
              </entry>
              
              <entry align="center">
                <para>5</para>
                <para>Permanently Unavailable
                  <footnote>
                    <para>Permanently unavailable is signaled by a zero value 
                    returned in the <emphasis>PE Unavailable Info</emphasis> 
                    of the <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS calls.</para>
                  </footnote>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry morerows="3"><?dbfo orientation="90"?><?dbfo rotated-width="1.5in"?>
                <para>
                  <emphasis>ibm,set-eeh-option</emphasis>
                </para>
              </entry>
              <entry morerows="1">
                <para>
                <emphasis>Function</emphasis> 2</para>
                <para>Release PE for</para>
                <para>
                  <emphasis>Load/Store</emphasis>
                </para>
              </entry>
              <entry>
                <para>Result</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>Transition from state 2 to 4</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis>Status
                  <footnote xml:id="pgfId-1146534">
                    <para>A 
                    <emphasis>Status</emphasis> of -3 is returned instead of 0
                    or -7 if an invalid PCI configuration address is used. An
                    invalid PCI configuration address is generally one which is
                    not a PE address or which is not assigned to the OS.
                    However, some platforms may allow resetting within the PE
                    or outside the PE, providing this does not violate other
                    requirements defined by this architecture. Also, some
                    legacy implementations may return a -1 or -3 instead of a
                    -7, but all implementations are required to implement the
                    -7 
                    <emphasis>Status</emphasis>, where appropriate.</para>
                  </footnote></emphasis>
                </para>
              </entry>
              <entry>
                <para>-3</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>-3</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
            </row>
            <row>
              <entry morerows="1">
                <para>
                <emphasis>Function</emphasis> 3</para>
                <para>Release PE for</para>
                <para>DMA</para>
              </entry>
              <entry>
                <para>Result</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>Transition from state 4 to 0</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis>Status</emphasis>
                  <emphasis>
                    <footnoteref linkend="pgfId-1146534" />
                  </emphasis>
                </para>
              </entry>
              <entry>
                <para>-3</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
            </row>
            <row>
              <entry morerows="3"><?dbfo orientation="90"?><?dbfo rotated-width="1.5in"?>
                <para>
                  <emphasis>ibm,set-slot-reset</emphasis>
                </para>
              </entry>
              <entry morerows="1">
                <para>
                <emphasis>Function</emphasis> 0</para>
                <para>Deactivate the</para>
                <para>reset to the PE
                <footnote xml:id="pgfId-1255960">
                  <para>In the case of the use of FLR by the platform to reset
                  the PE, the &#8220;activate&#8221; and
                  &#8220;deactivate&#8221; of the reset has a different meaning
                  than for the Hot Reset case. For FLR, the platform makes the
                  pulse of the FLR look like the Hot Reset case to the OS in
                  terms of the Reset state (See 
                  <xref linkend="dbdoclet.50569332_86249" /> for more
                  information).</para>
                </footnote></para>
              </entry>
              <entry>
                <para>Result</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>Transition from state 1 to 0
                <footnote xml:id="pgfId-1255982">
                  <para>The platform also removes the PE from the EEH Stopped
                  state, if applicable, on the transition from state 1 to state
                  0.</para>
                </footnote></para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis>Status</emphasis>
                  <emphasis>
                    <footnoteref linkend="pgfId-1146534" />
                  </emphasis>
                  
                </para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-3</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
            </row>
            <row>
              <entry morerows="1">
                <para>
                <emphasis>Function</emphasis> 1 or 3</para>
                <para>Activate the</para>
                <para>reset to the PE</para>
              </entry>
              <entry>
                <para>Result
                <emphasis>
                  <footnoteref linkend="pgfId-1236378" />
                </emphasis></para>
              </entry>
              <entry>
                <para>Transition from state 0 to 1</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>Transition from state 2 to 1</para>
              </entry>
              <entry>
                <para>Transition from state 4 to 1</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
              <entry>
                <para>no-op</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis>Status</emphasis>
                  <emphasis>
                  <footnoteref linkend="pgfId-1146534" />, 
                  <footnote xml:id="pgfId-1236378">
                    <para>For 
                    <emphasis>Function</emphasis> 3, if 
                    <emphasis>Function</emphasis> 3 is not implemented, then a 
                    <emphasis>Status</emphasis> of -3 is returned. For 
                    <emphasis>Function</emphasis> 3, if implemented in the RTAS
                    call, but not implemented for the specified PCI
                    configuration address, then a 
                    <emphasis>Status</emphasis> of -8 is returned. In either of
                    these cases, the PE state is not changed. If 
                    <emphasis>Function</emphasis> 3 is implemented, then the
                    platform indicates this by the 
                    <emphasis role="bold"><literal>
                    &#8220;ibm,reset-capabilities&#8221;</literal></emphasis> property in
                    the OF device tree.</para>
                  </footnote></emphasis>
                </para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>-7</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>The PE configuration address (
      <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
      for the domain is the PCI configuration address for the PE primary bus
      and is the same format as used for the ibm,read-pci-config and
      ibm,write-pci-config calls (see Requirement 
      <xref linkend="dbdoclet.50569332_13648" />), except that the Register
      field is set to 0. The PE configuration address is obtained as indicated
      in 
      <xref linkend="LoPAR.Platform" />.</para>
    
      <section xml:id="dbdoclet.50569332_27269">
        <title><emphasis>ibm,set-eeh-option</emphasis></title>
        
        <para>This call is used to enable and disable the EEH domain of a PE, to
        remove a PE from the MMIO Stopped state to continue 
        <emphasis>Load</emphasis> and 
        <emphasis>Store</emphasis> operations to the domain, and to remove a PE
        from the DMA Stopped state to continue DMA operations to the domain. The
        PE configuration address (
        <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
        for the PE is obtained as defined in 
        <xref linkend="dbdoclet.50569332_39444" />.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> RTAS must implement an 
                <emphasis>ibm,set-eeh-option</emphasis> call
                using the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_28980" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_28980">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,set-eeh-option</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,set-eeh-option</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>1</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>
                            <emphasis>Function</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Disable EEH option for the PE (no-op for PEs with PCI
                          Express IOAs)</para>
                          <para>1: Enable EEH option for the PE</para>
                          <para>2: Release the PE for 
                          <emphasis>Load</emphasis>/
                          <emphasis>Store</emphasis> operations</para>
                          <para>3: Release the PE for DMA operations</para>
                          <para>4: Enable EEH io-event interrupt for this PE</para>
                          <para>5: Disable EEH io-event interrupt for this PE</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>
                          <para>-7 Unexpected state change</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software and Platform Implementation Note:</emphasis> For
                platforms that enable EEH by default, 
                <emphasis>ibm,set-eeh-option Function</emphasis> 0 (disable EEH) is a
                no-op. However, 
                <emphasis>ibm,set-eeh-option Function</emphasis> 1 (enable EEH) is still
                required as a signalling method from the device driver to the platform
                that the device driver is at least EEH aware (see Requirement 
                <xref linkend="LoPAR.Platform" />).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> Software must use the 
                <emphasis>ibm,get-config-addr-info2</emphasis> RTAS call, when supported,
                to get the EEH domain span of the PE, otherwise software must use the 
                <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call in order to
                determine the span, and then software should attempt to perform all 
                <emphasis>ibm,set-slot-reset</emphasis>
                and
                
                <emphasis>ibm,set-eeh-option</emphasis>
                RTAS calls appropriately, based on the EEH
                capabilities and as governed by 
                <xref linkend="dbdoclet.50569332_19683" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If the EEH option is implemented
                for the specified PE configuration address, on a call to the
                
                <emphasis>ibm,set-eeh-option</emphasis>
                with a
                
                <emphasis>Function</emphasis>
                of 0 (disable EEH) the platform must do one of the
                following:</para>
          
                <itemizedlist>		      
                  <listitem>
                    <para>If any IOA in the PE is enabled (if any of the Bus Master, Memory
                    Space or I/O Space bits in the Command Register of the IOA&#8217;s
                    configuration space are 1), then do nothing and return a 
                    <emphasis>Status</emphasis> of 0 (Success).</para>
                  </listitem>
                  
                  <listitem>
                    <para>If the platform allows disabling of EEH and the disabling of EEH
                    for the PE violates another requirement relative to LPAR, then the
                    platform must not disable the EEH option for the specified PE
                    configuration address and must return a -7 (unexpected state change) or a
                    -1 (hardware error), with -7 preferred.</para>
                  </listitem>
                  
                  <listitem>
                    <para>If the platform allows disabling of EEH and the disabling of EEH
                    for the PE does not violate the other requirements relative to LPAR, then
                    clear the MMIO Stopped State and DMA Stopped State, and disable the EEH
                    option, for the specified PE configuration address.</para>
                  </listitem>
                  
                  <listitem>
                    <para>If the default for the platform is EEH enabled, then do nothing
                    and return a 
                    <emphasis>Status</emphasis> of 0 (Success).</para>
                  </listitem>
                </itemizedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_88517">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis>
                If the OS allows
                the DMA to be enabled for a PE that is in the DMA Stopped state without
                the use of a reset operation (that is, the use of the 
                <emphasis>ibm,set-eeh-option</emphasis> with a 
                <emphasis>Function</emphasis> of 3), the device driver must first do all
                necessary cleanup of its IOA to prevent the IOA from doing anything
                destructive when it starts DMA again.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If a device driver is going to
                enable EEH and the platform has not defaulted to EEH enabled, then it
                must do so before it does any operations with its IOA, including any
                configuration cycles or 
                <emphasis>Load</emphasis> or 
                <emphasis>Store</emphasis> operations.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If an EEH domain is enabled for a
                PE via the ibm,set-eeh-option RTAS call and if there are multiple IOAs or
                one or more multi-function IOAs in that PE, and if these functions are
                supported by multiple device drivers, then all of the device drivers for
                all the functions in that PE must be EEH enabled and be capable of
                coordinating EEH recovery procedures.</para>
                <para>
                <emphasis role="bold">Software implementation Note:</emphasis> Protection against
                startup errors (configuration cycles, etc.), are every bit as important
                as protection against errors during normal operations. Although the
                quantity of operations is not as great, there is more of a chance of
                latent errors showing up during the startup phase.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If the Slot Level EEH Event
                Interrupt option is not implemented for the PE, then return a 
                <emphasis>Status</emphasis> of -3 if 
                <emphasis>Function</emphasis> 4 or 5 is attempted.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_27269" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH with the Slot Level EEH Event Interrupt
                option:</emphasis>
                <emphasis>Function</emphasis> 4 and 5 must be implemented for all PE under
                nodes that contain the 
                <emphasis role="bold"><literal>&#8220;ibm,io-events-capable&#8221;</literal></emphasis> property.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_86249">
        <title><emphasis>ibm,set-slot-reset</emphasis></title>
        
        <para>This call is used to reset a PE. The PE configuration address (
        <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
        for the PE is obtained as defined in 
        <xref linkend="dbdoclet.50569332_39444" />. All PEs have the capability
        of being reset independently. Resets outside or within the PE are not
        architected, but may be allowed by the platform implementation, providing
        that it does not violate other requirements of this architecture.</para>
        <para>The platform may use one of two methods to reset a PCI Express PE,
        when the 
        <emphasis>ibm,set-slot-reset</emphasis> RTAS call is made with the 
        <emphasis>Function</emphasis> 1/
        <emphasis>Function</emphasis> 0 (activate the reset/deactivate the
        reset).</para>
        
        <itemizedlist>		      
          <listitem>
            <para>If the PE is a single function of a multi-function IOA, then the
            Function Level Reset (FLR) option is required to be implemented by the
            function, and the platform uses FLR to reset the function. When the
            platform uses FLR instead of Hot Reset to reset a PCI Express PE, the
            platform provides the 
            <emphasis role="bold"><literal>&#8220;ibm,pe-reset-is-flr&#8221;</literal></emphasis> property in the
            function&#8217;s OF Device Tree node, and provides the same EEH recovery
            model to the software, as in the Hot Reset case, and as defined by 
            <xref linkend="dbdoclet.50569332_19683" />. The property is provided in
            the case where there may be slightly different device-specific reset
            recoveries by the software for the FLR case.</para>
            <para>
            <emphasis role="bold">Software Implementation Note:</emphasis> The platform does not
            monitor writes to the FLR bit of an IOA, and so OS or Device Driver
            writes directly to the FLR bit on an IOA will not affect the PE State as
            shown in 
            <xref linkend="dbdoclet.50569332_19683" />.</para>
          </listitem>
          
          <listitem>
            <para>Otherwise, a PCI Express Hot Reset is used.</para>
          </listitem>
        </itemizedlist>		      
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> The 
                <emphasis>ibm,set-slot-reset</emphasis> call must be implemented using the
                argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_42044" />.</para>
                
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_42044">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,set-slot-reset</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,set-slot-reset</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>1</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>
                            <emphasis>Function</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Deactivate the reset to the PE</para>
                          <para>1: Activate the reset to the PE (for PCI Express, if the
                          platform uses FLR to reset the PE, the platform provides the 
                          <emphasis role="bold"><literal>&#8220;ibm,pe-reset-is-flr&#8221;</literal></emphasis> property
                          in the function&#8217;s OF Device Tree node)</para>
                          <para>3: (optional) Activate the reset to the PE, using a PCI
                          Express Fundamental Reset</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>
                          <para>-7: Unexpected state change</para>
                          <para>-8: Fundamental Reset not defined for this configuration
                          address</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> After activation of the reset (
                <emphasis>Function</emphasis> 1 or 3), software must delay the
                deactivation of the reset (
                <emphasis>Function</emphasis> 0) to that PE via the 
                <emphasis>ibm,set-slot-reset</emphasis> call,
                until the minimum reset signal active time has elapsed, as designated by
                the bus specifications for the particular type bus or buses involved (100
                millisecond for PCI).</para>
                <para>
                  <emphasis role="bold">Software Implementation Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>The device driver is responsible for any additional clean up
                    required beyond that provided by a reset to the IOA. For PCI Express, the
                    clean up may be slightly different based on whether the platform used FLR
                    or Hot Reset to reset the PE. When FLR is used, the platform provides the      
                    <emphasis role="bold"><literal>&#8220;ibm,pe-reset-is-flr&#8221;</literal></emphasis> property in the
                    function&#8217;s OF Device Tree node.</para>
                  </listitem>
          
                  <listitem>
                    <para>The software is responsible for quiescing (stopping) any MMIO 
                    <emphasis>Load</emphasis> and 
                    <emphasis>Store</emphasis> activities to the PE prior to resetting the
                    PE.</para>
                  </listitem>
          
                  <listitem>
                    <para>If the platform uses FLR to implement the PE reset, software may
                    need to understand that this is a pulse and not a solid level, such that
                    the adapter is not held at reset during the time from the call with 
                    <emphasis>Function</emphasis> 1 and the call with 
                    <emphasis>Function</emphasis> 0.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> After deactivation of the reset (
                <emphasis>Function</emphasis> 0), software must delay access to that PE
                until the minimum time after reset that is required for the PE to be come
                stable has elapsed, as designated by the bus specifications for the
                particular type bus or buses involved (for example, 1.5 seconds for PCI
                Express).</para>
                <para>
                  <emphasis role="bold">Software Implementation Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>Different implementations of PCI Express may require different
                    amounts of delay in order to traverse the I/O fabric since individual
                    component delays are plug-in card specific.</para>
                  </listitem>
          
                  <listitem>
                    <para>The <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call returns a 
                    <emphasis>PE Reset State</emphasis> of 5 (PE is unavailable) while any
                    reset delay time is happening for hardware outside the PE.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If the 
                <emphasis>ibm,set-slot-reset</emphasis> call is called with a 
                <emphasis>Function</emphasis> of 0 (deactivate) and any reset to the reset
                domain specified by the 
                <emphasis>PE configuration address</emphasis> is active, then the RTAS
                call must de-activate all resets to that PE configuration address.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> If the 
                <emphasis>ibm,set-slot-reset</emphasis> call is called with a 
                <emphasis>Function</emphasis> of 0 (deactivate) and there is no operation
                to be performed (for example, the reset to the reset domain specified by
                the PE configuration address is not active), then the RTAS call must
                return a 
                <emphasis>Status</emphasis> of 0 (success).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> When the 
                <emphasis>ibm,set-slot-reset</emphasis> call is called with a 
                <emphasis>Function</emphasis> of 1 or 3 (activate) with a valid PHB Unit
                ID and config_addr and it is the case that FLR is not being used by the
                platform to reset the PE, then the RTAS call must activate the reset to
                the reset domain as designated by the PE configuration address, if not
                already activated.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> When the 
                <emphasis>ibm,set-slot-reset</emphasis> RTAS call implements 
                <emphasis>Function</emphasis> 3, the platform must also provide the 
                <emphasis role="bold"><literal>&#8220;ibm,reset-capabilities&#8221;</literal></emphasis> property in the 
                <emphasis>RTAS</emphasis> node of the OF device tree.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> When the 
                <emphasis>ibm,set-slot-reset</emphasis> call is called with a 
                <emphasis>Function</emphasis> of 0 (deactivate) with a valid PHB Unit ID
                and config_addr and if the corresponding PE is in the MMIO Stopped or DMA
                Stopped state, then the RTAS call must bring that PE as designated by the
                PE configuration address out of the MMIO Stopped and DMA Stopped states
                and clear any applicable platform EEH status state.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> When the platform uses FLR to
                reset a PCI Express PE (
                <emphasis>ibm,set-slot-reset</emphasis> call with a 
                <emphasis>Function</emphasis> of 1(activate) followed by a call with 
                <emphasis>Function</emphasis> 0 (deactivate)), then the platform must
                provide the 
                <emphasis role="bold"><literal>&#8220;ibm,pe-reset-is-flr&#8221;</literal></emphasis> property in the
                function&#8217;s OF Device Tree node, and the platform must always use
                FLR to reset a PE which contains this property in the OF Device
                Tree.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_25028">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_86249" 
            xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis>
                For a PCI Express
                PE, the platform must provide the EEH recovery model to the software, as
                defined by 
                <xref linkend="dbdoclet.50569332_19683" />, regardless of whether Hot
                Reset or FLR is used to reset the PE.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
      </section>
      
      <section xml:id="dbdoclet.50569332_87326">
        <title><emphasis>ibm,read-slot-reset-state2</emphasis></title>
        <para>This call queries the state of a PE, and dynamically determines
        whether a PCI configuration address corresponds to a PE primary bus (that
        is, if it is the PE configuration address). In addition, when the 
        <emphasis>PE Reset State</emphasis> parameter is a 5 (PE is unavailable),
        then the 
        <emphasis>PE Unavailable Info</emphasis> indicates an approximate amount
        of time for which the PE might be unavailable. The PE configuration
        address (
        <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
        for the PE is obtained as defined in 
        <xref linkend="dbdoclet.50569332_39444" />.</para>
        <para>When the 
        <emphasis>ibm,get-config-addr-info2</emphasis> RTAS call is implemented,
        that call can be used instead of this one to determine the PE
        configuration address. See 
        <xref linkend="dbdoclet.50569332_68098" /> and 
        <xref linkend="LoPAR.Platform" />.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_87326" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis>ibm,read-slot-reset-state2</emphasis> call
                must be implemented using the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_80186" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_80186">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,read-slot-reset-state2</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,read-slot-reset-state2</emphasis> (see Firmware
                          Implementation note, below)</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>4: Always allowed.</para>
                          <para>5: May be allowed, depending on the value of the 
                          <emphasis role="bold"><literal>
                          &#8220;ibm,read-slot-reset-state-functions&#8221;</literal></emphasis> property
                          in the 
                          <emphasis>RTAS</emphasis> node of the device tree (
                          <xref linkend="LoPAR.DeviceTree" />).</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Configuration Space 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="4">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PE Reset State</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Except for a 
                          <emphasis>PE Reset State</emphasis> of 5, this output is not
                          valid unless the 
                          <emphasis>Config_addr Capabilities</emphasis> output is a 1 and
                          the 
                          <emphasis>Status</emphasis> is a 0.</para>
                          <para>0: Reset deactivated and the PE is not in the MMIO
                          Stopped or DMA Stopped state</para>
                          <para>1: Reset activated and the PE is not in the MMIO Stopped
                          or DMA Stopped states</para>
                          <para>2: The PE is in the MMIO Stopped and DMA Stopped states
                          with the reset deactivated and the 
                          <emphasis>Load</emphasis>/
                          <emphasis>Store</emphasis> path is disabled</para>
                          <para>4: The PE is in the DMA Stopped state with the reset
                          deactivated and the 
                          <emphasis>Load</emphasis>/
                          <emphasis>Store</emphasis> path is enabled</para>
                          <para>5: PE is unavailable</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr Capabilities</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>This output is not valid if the 
                          <emphasis>PE Reset State is a 5.</emphasis></para>
                          <para>0: EEH not supported for the 
                          <emphasis>Config_addr</emphasis></para>
                          <para>1: EEH supported for the 
                          <emphasis>Config_addr</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>PE Unavailable Info</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>This output is not valid unless the 
                          <emphasis>Config_addr Capabilities</emphasis> output is a 1 and
                          the 
                          <emphasis>PE Reset State</emphasis> is a 5 and the 
                          <emphasis>Status</emphasis> is a 0, in which case the value of
                          this parameter is a 0 if the PE is permanently unavailable, and
                          non-zero if a recovery is in progress and there is an expected
                          availability after the recovery; the non-0 value in this case
                          is the number of milliseconds that the recovery is expected to
                          take.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>PE Recovery Info</para>
                        </entry>
                        <entry>
                          <para>This output is only valid if the 
                          <emphasis role="bold"><literal>
                          &#8220;ibm,read-slot-reset-state-functions&#8221;</literal></emphasis> property
                          in the 
                          <emphasis>RTAS</emphasis> node of the device tree indicates that
                          it is implemented and the call is made with a 
                          <emphasis>Number Outputs</emphasis> of at least 5 and the 
                          <emphasis>PE Reset State</emphasis> is a value of 2. This is a
                          32-bit field with bit significance, as follows:</para>
                          <para>&#160;</para>
                          <para>Bits 0:27 - Reserved</para>
                          <para>&#160;</para>
                          <para>Bits 28:29 - PE platform reset type. Only valid when bit
                          31 of this field is a value of 1.</para>
                          <para>Bits 28:29 = 0b00: Firmware does not implement these
                          bits. Reset type is most likely a Hot Reset.</para>
                          <para>Bits 28:29 = 0b01: Platform used a Hot Reset to reset the
                          PE.</para>
                          <para>Bits 28:29 = 0b10: Platform used a Fundamental Reset to
                          reset the PE.</para>
                          <para>Bits 28:29 = 0b11: Platform used an FLR to reset the
                          PE.</para>
                          <para>&#160;</para>
                          <para>Bit 30 - Retry Count Hint</para>
                          <para>Bit 30 = 0: Either the PE associated with the 
                          <emphasis>Config_addr</emphasis> was the source of this PE
                          entering the 
                          <emphasis>PE Reset State</emphasis> of 2, or the platform has
                          not determined whether this PE was the source or not.</para>
                          <para>Bit 30 = 1: The platform has determined that the PE
                          associated with the 
                          <emphasis>Config_addr</emphasis> was not the source of this PE
                          entering the 
                          <emphasis>PE Reset State</emphasis> of 2. That is, setting this
                          bit indicates that this PE entered the 
                          <emphasis>PE Reset State</emphasis> of 2 as a side-effect of
                          some error outside of this PE&#8217;s domain. Software may use
                          this hint to not count this occurrence of the 
                          <emphasis>PE Reset State</emphasis> of 2 as part of any EEH
                          error recovery retry count that it might be keeping for this
                          PE.</para>
                          <para>&#160;</para>
                          <para>Bit 31 - Reset Status</para>
                          <para>Bit 31 = 0: PE was not reset as a result of the platform
                          transition to 
                          <emphasis>PE Reset State</emphasis> of 2.</para>
                          <para>Bit 31 = 1: PE was reset as a result of the platform
                          transition to 
                          <emphasis>PE Reset State</emphasis> of 2. If the PE is not below
                          a node marked with the special value of the 
                          <emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> property of 
                          <emphasis role="bold"><literal>&#8220;reserved&#8221;</literal></emphasis>, then after
                          deactivation of the platform-initiated PE reset, the platform
                          is required to delay access to that PE until the minimum time
                          after reset that is required for the PE to be come stable has
                          elapsed, as designated by the bus specifications for the
                          particular type bus or buses involved (for example, 1.5 seconds
                          for PCI Express), by returning 
                          <emphasis>PE Reset State</emphasis> of 5 with 
                          <emphasis>PE Unavailability Info</emphasis> non-zero
                          (temporarily unavailable) until that time has elapsed). If the
                          PE is below a node marked with the special value of the 
                          <emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> property of 
                          <emphasis role="bold"><literal>&#8220;reserved&#8221;</literal></emphasis>, then after
                          deactivation of the platform-initiated PE reset, the firmware
                          immediately (without delay) transitions the PE to the 
                          <emphasis>PE Reset State</emphasis> of 2, and it is the
                          controlling software that is required to do the bus-specific
                          delays.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Firmware Implementation Note:</emphasis> The argument call
                buffer structure and requirements for this call are the same as for the
                old (removed from this architecture) 
                <emphasis>ibm,read-slot-reset-state</emphasis> call, except for the last
                output parameter. Therefore, it is possible for platforms that still
                require the old 
                <emphasis>ibm,read-slot-reset-state</emphasis> RTAS call to implement the 
                <emphasis>ibm,read-slot-reset-state</emphasis> and
                <emphasis>ibm,read-slot-reset-state2</emphasis> calls with the same RTAS
                token and use the number of output parameters to determine whether or not
                to implement the PE
                <emphasis>Unavailable Info</emphasis> parameter.</para>
                <para>
                  <emphasis role="bold">Platform Implementation Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>The <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call only returns a 
                    <emphasis>PE Reset State</emphasis> of 1 (Reset activated and the PE is
                    not in the MMIO Stopped or DMA Stopped state) when the reset may be
                    removed by software; that is, if the error is potentially recoverable. If
                    the firmware has detected a hardware error that is such that the reset to
                    the device cannot be removed or is not safe to remove, the 
                    <emphasis>ibm,read-slot-reset-state2</emphasis> does not return a 
                    <emphasis>PE Reset State</emphasis> of 1, but instead returns a 
                    <emphasis>PE Reset State</emphasis> of 5 (PE is unavailable) along with PE
                    <emphasis>Unavailable Info</emphasis> of 0 (PE is permanently
                    unavailable).</para>
                  </listitem>
          
                  <listitem>
                    <para>The <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call should never
                    return a -1 (hardware error), but should instead return a 
                    <emphasis>PE Reset State</emphasis> of 5 (PE is unavailable) with a 
                    <emphasis>PE Unavailable Info</emphasis> of 0 (PE is permanently
                    unavailable).</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_87326" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call must return a 
                <emphasis>Reset State</emphasis> value of 5 (PE is unavailable) under any
                of the following conditions:</para>
          
                <orderedlist numeration="loweralpha">		      
                  <listitem xml:id="dbdoclet.50569332_63831">
                    <para>Firmware has
                    determined that communications with the PE is not available or the path
                    to the PE cannot be traversed at the current time</para>
                  </listitem>
          
                  <listitem>
                    <para>The <emphasis>ibm,slot-error-detail</emphasis> RTAS call has been called with
                    a 
                    <emphasis>Function</emphasis> of 2, and none of the resetting conditions
                    specified in Requirement 
                    <xref linkend="dbdoclet.50569332_33750" /> have been met.</para>
                  </listitem>
                </orderedlist>		      
          
                <para>
                  <emphasis role="bold">Software Implementation Notes:</emphasis>
                </para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The condition under Requirement 
                    <xref linkend="dbdoclet.50569332_31824" xrefstyle="select: nopage"/><xref linkend="dbdoclet.50569332_63831"  xrefstyle="select: labelnumber"/>
                    may be temporary, with a
                    recovery time in the range of seconds (for example, as little as 3
                    seconds or up to couple of minutes). Software may chose to delay the time
                    indicated in the 
                    <emphasis>PE Unavailable Info</emphasis> and issue the 
                    <emphasis>ibm,read-slot-reset-state2</emphasis> call again when a
                    temporary condition exists. The condition may also be clearable with a
                    power cycle of the PE, in which case the firmware may return a 
                    <emphasis>Status</emphasis> of 990x to the 
                    <emphasis>set-power-level</emphasis> RTAS call, to delay long enough to
                    clear the temporary condition.</para>
                  </listitem>
          
                  <listitem>
                    <para><emphasis>Config_addr Capabilities</emphasis> may be indeterminate when
                    the <emphasis>PE Reset State</emphasis> of 5 (PE is unavailable) is returned.
                    Software should ignore the 
                    <emphasis>Config_addr Capabilities</emphasis> return when the 
                    <emphasis>PE Reset State</emphasis> of 5 is returned.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_31824">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_87326" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>If the 
                <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call must return a 
                <emphasis>PE Reset State</emphasis> value of 5 (PE is unavailable) then it
                must indicate in the 
                <emphasis>PE Unavailable Info</emphasis> parameter one of the
                following:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>A value of zero, if there is no error recovery in progress that
                    makes the PE available in any predictable amount of time (that is, the PE
                    is &#8220;permanently&#8221; unavailable; for example, until a power
                    cycle or until a repair action).</para>
                  </listitem>
          
                  <listitem>
                    <para>A non-zero value, indicating the approximate time in
                    milliseconds after which the path to the PE is expected to become
                    available again.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_87326" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call must return a 
                <emphasis>Config_addr Capabilities</emphasis> of 1 (EEH supported for the 
                <emphasis>Config_addr</emphasis>) for every 
                <emphasis>Config_addr</emphasis> within a PE and for the PE configuration
                address.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_87326" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call must comply with
                the state transitions defined in 
                <xref linkend="dbdoclet.50569332_19683" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
      </section>
      
      <section xml:id="dbdoclet.50569332_68098">
        <title><emphasis>ibm,get-config-addr-info2</emphasis></title>
        
        <para>This call is used obtain information about fabric configuration
        addresses, given the PCI configuration address. See 
        <xref linkend="LoPAR.Platform" /> for more information on PEs and
        determining PE configuration addresses.</para>
        <para>The PCI configuration address (
        <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
        for the call is defined by 
        <xref linkend="dbdoclet.50569332_36386" />.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68098" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,get-config-addr-info2</emphasis> call
                must be implemented using the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_14652" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14652">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,get-config-addr-info2</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,get-config-addr-info2</emphasis> (see Firmware
                          Implementation note, below)</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>2</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Config_addr</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Configuration Space 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>
                            <emphasis>Function</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>See 
                          <xref linkend="dbdoclet.50569332_77574" /> for available
                          functions.</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>0: Success</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Info</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>See 
                          <xref linkend="dbdoclet.50569332_77574" /> for values.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_68098" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>ibm,get-config-addr-info2</emphasis> RTAS call must return the 
                <emphasis>Data</emphasis> output as per 
                <xref linkend="dbdoclet.50569332_77574" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_77574">
                  <title>Input and 
                  <emphasis>ibm,get-config-addr-info2 Function</emphasis>
                  <emphasis>Info</emphasis> Output</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">
                            <emphasis>Function</emphasis> Input</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Definition</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">
                            <emphasis>Info</emphasis> Output</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>0</para>
                        </entry>
                        <entry>
                          <para>Get PE configuration address</para>
                        </entry>
                        <entry>
                          <para>PE configuration address (as defined by 
                          <xref linkend="dbdoclet.50569332_36386" />). Result returned in
                          
                          <emphasis>Info</emphasis> output is:</para>
                          <para>Equal to the 
                          <emphasis>Config_addr</emphasis> input if there is no bridge or
                          switch between the IOA function (endpoint) and the PE primary
                          bus.</para>
                          <para>Equal to the 
                          <emphasis>Config_addr</emphasis> of the PE primary bus if there
                          is a bridge or switch between the IOA function and the PE
                          primary bus.</para>
                          <para>Undefined if 
                          <emphasis>Config_addr</emphasis> is not in a PE (query for PE
                          state by using 
                          <emphasis>Function</emphasis> 1 first or by 
                          <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call). A 
                          <emphasis>Status</emphasis> of -3 (Parameter Error) is returned
                          in this case, also.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>1</para>
                        </entry>
                        <entry>
                          <para>Query shared PE state</para>
                        </entry>
                        <entry>
                          <para>0: 
                          <emphasis>Config_addr</emphasis> is not in a PE (EEH not
                          supported for the 
                          <emphasis>Config_addr</emphasis>).</para>
                          <para>1: Not shared (Only one IOA function in the PE).</para>
                          <para>2: Shared (More than one IOA function in the PE).</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_43482">
        <title><emphasis>ibm,slot-error-detail</emphasis></title>
        
        <para>This call combines device driver information, as gathered by the
        device driver prior to this call, with information derived by firmware
        from the platforms I/O infrastructure to create a detailed event log
        concerning a recoverable EEH event. In this way, both OS and platform
        maintenance applications have access to all the information about a given
        event. In addition, the OS can mark a PE configuration address as being
        in an unavailable state due to excessive errors.</para>
        <para>The caller supplies the device driver information, referenced by
        the 
        <emphasis>Device_Driver_Error_Buffer</emphasis> argument. The 
        <emphasis>Returned_Error_Buffer</emphasis> argument points to a buffer
        that this call fills with valid error log data as defined in the error
        log format section. Different platforms log using different versions of
        the error logging format. The error log data may include platform
        specific data as well as device driver data passed in the 
        <emphasis>Device_Driver_Error_Buffer</emphasis>. Regardless of the error
        log version used, the data in the 
        <emphasis>Returned_Error_Buffer</emphasis> is in an extended log format as
        defined in 
        <xref linkend="LoPAR.Error" />. When the call returns data
        for version 6 or greater, the device driver error buffer data is included
        as the last User Data section. The device driver data in the return
        buffer may be truncated from what is passed by the device driver or
        completely eliminated as necessary to ensure that the returned buffer
        length is not exceeded.</para>
        <para>The 
        <emphasis>Config_addr</emphasis> supplied is the PE configuration address
        (
        <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
        for the PE, obtained as defined in 
        <xref linkend="dbdoclet.50569332_39444" />, or a configuration address
        within the PE. The I/O fabric information that is captured by the
        platform consists of useful PCI configuration state at and above the
        supplied 
        <emphasis>Config_addr</emphasis>.</para>
        <para>This RTAS call supports both plug-in PCI cards and built-in PCI
        IOAs.</para>
        <para>In this section, the term unavailable, when applied to a PE, means
        that 
        <emphasis>ibm,read-slot-reset-state2</emphasis> would return a PE Reset
        State of 5 (PE is unavailable) at the current time.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EEH option:</emphasis> The
                argument call buffer for the 
                <emphasis>ibm,slot-error-detail</emphasis> call must correspond to the
                definition given in 
                <xref linkend="dbdoclet.50569332_46549" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_46549">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,slot-error-detail</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="10">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,slot-error-detail</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Number Inputs</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>8</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>Configuration address (Register numbers 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>
                            <emphasis>Device_Driver_Error_Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of an error log buffer containing device
                          driver debug data. This data is integrated into the final error
                          log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Device_Driver_Error_Buffer_Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Length of the 
                          <emphasis>Device_Driver_Error_Buffer</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Returned_Error_Buffer</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Real address of an error log buffer to contain a
                          compliant error log entry composed by the RTAS</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Returned_Error_Buffer_Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Length of the 
                          <emphasis>Returned_Error_Buffer</emphasis></para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>
                            <emphasis>Function</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1: Temporary Error</para>
                          <para>2: Permanent Error</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>1: No Error Log Returned</para>
                          <para>0: Success</para>
                          <para>-1: Hardware Error (cannot create log)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The 
                <emphasis>Returned_Error_Buffer</emphasis> format must be the same as
                implemented by 
                <emphasis>event-scan</emphasis> on the platform.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>To prevent standard error log record
                truncation, the 
                <emphasis>Returned_Error_Buffer_Length</emphasis> must equal the value of
                the OF device tree property 
                <emphasis role="bold"><literal>&#8220;rtas-error-log-max&#8221;</literal></emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_25140">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>If the PE corresponding to the 
                <emphasis>Config_addr</emphasis> is in the MMIO Stopped or DMA Stopped
                state, then the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call must return a 
                <emphasis>Status</emphasis> of 0 and an error log that defines the FRU or
                FRUs to which the error is isolated.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_61891">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>If the communications with the 
                <emphasis>Config_addr</emphasis> is not available, the path to the 
                <emphasis>Config_addr</emphasis> cannot be traversed at the current time,
                or this call has previously made with a 
                <emphasis>Function</emphasis> of 2 and none of the conditions that reset
                this state have been met (that is the PE is unavailable), then the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call must return a 
                <emphasis>Status</emphasis> of 0 and an error log that defines the FRU or
                FRUs to which the error is isolated.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>If the conditions in Requirements 
                <xref linkend="dbdoclet.50569332_25140" /> and 
                <xref linkend="dbdoclet.50569332_61891" /> are not met, then the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call must return a 
                <emphasis>Status</emphasis> of 1, no error found, with no error log entry
                returned.</para>
                <para>
                <emphasis role="bold">Software and Platform Implementation Note:</emphasis> In some
                cases, the platform may return an information-only error log to meet
                Requirements 
                <xref linkend="dbdoclet.50569332_25140" /> and 
                <xref linkend="dbdoclet.50569332_61891" />. For example, in some
                implementations this might be appropriate if the actual error was already
                logged via another RTAS call or this call was previously made with a 
                <emphasis>Function</emphasis> of 2 and none of the conditions that reset
                this state have been met.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para>Once a PE is unavailable and in the
                absence of any state-resetting action by the OS that clears the
                corresponding PE configuration address EEH error (for example, reset or
                power cycle), the platform must return an error log in response to the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para>Once a PE has experienced a
                state-resetting action by the OS that clears the corresponding PE
                configuration address EEH error (for example, reset or power cycle), that
                makes the PE available, the platform must return a 
                <emphasis>Status</emphasis> of 1, no error found, with no error log entry
                in response to the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para>If the <emphasis>ibm,slot-error-detail</emphasis> RTAS call 
                <emphasis>Device_Driver_Error_Buffer_Length</emphasis> argument is
                non-zero, indicating the existence of optional device driver error data,
                the referenced buffer must contain an extended event log as defined in 
                <xref linkend="LoPAR.Error" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
              <listitem>
                <para><emphasis>(Requirement Number Reserved For
                Compatibility)</emphasis></para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
              <listitem>
                <para>When the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call returns an extended
                log debug record in the buffer specified by the 
                <emphasis>Returned_Error_Buffer</emphasis> argument as mandated by
                Requirements 
                <xref linkend="dbdoclet.50569332_25140" /> and 
                <xref linkend="dbdoclet.50569332_61891" /> it must truncate the record at
                the length specified by the 
                <emphasis>Returned_Error_Buffer_Length</emphasis> argument.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_33750">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
              <listitem>
                <para>If a <emphasis>Function</emphasis> of 2 is passed to the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call, RTAS must
                unconditionally set the state of the PE corresponding to the 
                <emphasis>Config_addr</emphasis> to permanently unavailable; that is, any
                subsequent calls to
                <emphasis>ibm,read-slot-reset-state2</emphasis> return a PE Reset State of
                5 (PE is unavailable) with the 
                <emphasis>PE Unavailable Info</emphasis> argument set to zero.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
              <listitem>
                <para>RTAS must not change a PE Reset state
                of permanently unavailable unless one of the following occur:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>A PCI Hot Plug condition for the slot is encountered (as
                    determined by the power being turned off and then on for the slot)</para>
                  </listitem>
          
                  <listitem>
                    <para>The power domain is power cycled for another reason (for
                    example, a power down of the OS image that owns the IOA)</para>
                  </listitem>
          
                  <listitem>
                    <para>The state is cleared by a partition reboot or a dynamic LPAR
                    reassignment of the PCI configuration address.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
              <listitem>
                <para>After a PE enters the MMIO and DMA
                Stopped States due to an error, the platform must keep cached error
                information relative to that error, for reporting via the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call, until any one of the
                following events occurs:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The <emphasis>ibm,slot-error-detail</emphasis> RTAS call is called and the
                    error information is returned.</para>
                  </listitem>
          
                  <listitem>
                    <para>The reset to the PE is activated via the 
                    <emphasis>ibm,set-slot-reset</emphasis> RTAS call.</para>
                  </listitem>
          
                  <listitem>
                    <para>The removal of the PE from the DMA Stopped State via 
                    <emphasis>Function</emphasis> 3 of the 
                    <emphasis>ibm,set-eeh-option</emphasis> RTAS call.</para>
                  </listitem>
          
                  <listitem>
                    <para>The start of a DR operation as signalled by the calling of 
                    <emphasis>set-indicator</emphasis> with 
                    <emphasis>isolation-state</emphasis> set to isolate.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
              <listitem>
                <para>Prior to calling the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call, the PE which
                includes the 
                <emphasis>Config_addr</emphasis> must not be in the MMIO Stopped State, if
                the maximum amount of useful information is to be captured, as defined by
                Requirement 
                <xref linkend="dbdoclet.50569332_48077" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_48077">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
              <listitem>
                <para>The firmware implementing the 
                <emphasis>ibm,slot-error-detail</emphasis> is responsible for gathering
                the PCI fabric configuration space registers, including those at the
                specified 
                <emphasis>Config_addr</emphasis>, and also any other non-PCI I/O fabric
                registers that might be useful for debug purposes (for example, internal
                PHB registers), with the suggested appropriate minimum set of PCI
                configuration registers captured for each PCI device being as indicated
                in 
                <xref linkend="dbdoclet.50569332_76787" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76787">
                  <title>Suggested Minimum PCI Configuration Registers to
                  Capture for 
                  <emphasis>ibm,slot-error-detail</emphasis>
                  </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">Data Structure</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Offset within the Data
                            Structure</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Register</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry morerows="5">
                          <para>Base PCI Configuration Space Header</para>
                          <para>(for all PCI devices)</para>
                        </entry>
                        <entry>
                          <para>0x00</para>
                        </entry>
                        <entry>
                          <para>Vendor ID</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x02</para>
                        </entry>
                        <entry>
                          <para>Device ID</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x04</para>
                        </entry>
                        <entry>
                          <para>Command</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x06</para>
                        </entry>
                        <entry>
                          <para>Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x08</para>
                        </entry>
                        <entry>
                          <para>Revision ID</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x09</para>
                        </entry>
                        <entry>
                          <para>Class Code</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>Type 0 Configuration Space Header</para>
                          <para>(for non-PCI bridges only)</para>
                        </entry>
                        <entry>
                          <para>0x2C</para>
                        </entry>
                        <entry>
                          <para>Subsystem Vendor ID</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x2E</para>
                        </entry>
                        <entry>
                          <para>Subsystem ID</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Type 1 Configuration Space Header</para>
                          <para>(for PCI bridges only)</para>
                        </entry>
                        <entry>
                          <para>0x1E</para>
                        </entry>
                        <entry>
                          <para>Secondary Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="1">
                          <para>PCI-X Capabilities List</para>
                          <para>(for all PCI-X devices)</para>
                        </entry>
                        <entry>
                          <para>0x02</para>
                        </entry>
                        <entry>
                          <para>PCI-X Command (Type 0 Configuration Header)</para>
                          <para>PCI-X Secondary Status (Type 1 Configuration
                          Header)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x04</para>
                        </entry>
                        <entry>
                          <para>PCI-X Status (Type 0 Configuration Header)</para>
                          <para>PCI-X Bridge Status (Type 1 Configuration Header)</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="12">
                          <para>PCI Express Capabilities Structure</para>
                          <para>(for all PCI Express devices)</para>
                        </entry>
                        <entry>
                          <para>0x02</para>
                        </entry>
                        <entry>
                          <para>PCI Express Capabilities</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x04</para>
                        </entry>
                        <entry>
                          <para>Device Capabilities</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x08</para>
                        </entry>
                        <entry>
                          <para>Device Control</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x0A</para>
                        </entry>
                        <entry>
                          <para>Device Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x0C</para>
                        </entry>
                        <entry>
                          <para>Link Capabilities</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x10</para>
                        </entry>
                        <entry>
                          <para>Link Control</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x12</para>
                        </entry>
                        <entry>
                          <para>Link Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x14</para>
                        </entry>
                        <entry>
                          <para>Slot Capabilities</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x18</para>
                        </entry>
                        <entry>
                          <para>Slot Control</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x1A</para>
                        </entry>
                        <entry>
                          <para>Slot Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x1C</para>
                        </entry>
                        <entry>
                          <para>Root Control</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x1E</para>
                        </entry>
                        <entry>
                          <para>Root Capabilities</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x20</para>
                        </entry>
                        <entry>
                          <para>Root Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry morerows="11">
                          <para>Advanced Error Reporting Capability</para>
                          <para>(for all devices implementing AER)</para>
                        </entry>
                        <entry>
                          <para>0x00</para>
                        </entry>
                        <entry>
                          <para>PCI Express Enhanced Capability Header</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x04</para>
                        </entry>
                        <entry>
                          <para>Uncorrectable Error Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x08</para>
                        </entry>
                        <entry>
                          <para>Uncorrectable Error Mask</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x0C</para>
                        </entry>
                        <entry>
                          <para>Uncorrectable Error Severity</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x10</para>
                        </entry>
                        <entry>
                          <para>Correctable Error Status</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x14</para>
                        </entry>
                        <entry>
                          <para>Correctable Error Mask</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x18</para>
                        </entry>
                        <entry>
                          <para>Advanced Error Capabilities and Control</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x1C</para>
                        </entry>
                        <entry>
                          <para>Header Log</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x2C</para>
                        </entry>
                        <entry>
                          <para>Root Error Command (Root Ports only)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x30</para>
                        </entry>
                        <entry>
                          <para>Root Error Status (Root Ports only)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x34</para>
                        </entry>
                        <entry>
                          <para>Correctable Error Source Identification (Root Ports
                          only)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>0x36</para>
                        </entry>
                        <entry>
                          <para>Error Source Identification (Root Ports only)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
              <listitem>
                <para>If the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call is made with the PE
                in the PE state of 2 (as defined by 
                <xref linkend="dbdoclet.50569332_19683" />), then the platform must not
                remove the PE from that state in order to probe the PCI fabric.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_67249">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43482" 
            xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
              <listitem>
                <para>If the <emphasis>ibm,slot-error-detail</emphasis> RTAS call is made with the PE
                in the PE state of 4 (as defined by 
                <xref linkend="dbdoclet.50569332_19683" />), then the 
                <emphasis>ibm,slot-error-detail</emphasis> RTAS call must return with the
                PE in the PE state of 4, except that if an error occurs in the course of
                probing the PCI fabric that requires a reset of the PE by the platform,
                then discontinue probing, return a Status of 0 or 1 (as appropriate), and
                return the PE in the PE state of 2.</para>
                <para>
                  <emphasis role="bold">Software and Platform Implementation Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>In Requirement 
                    <xref linkend="dbdoclet.50569332_67249" />, it is possible, as a part of
                    the firmware probing the fabric, that the PE will transition temporarily
                    to a PE state of 2, in the case where another EEH event occurs as part of
                    the firmware probing the fabric. If the EEH event does not require a
                    reset of the PE for these subsequent EEH events, then the firmware may
                    transition the PE back to the PE state of 4, to continue probing. Several
                    of these PE state 4-&gt;2-&gt;4 events may occur as a result of probing
                    the fabric.</para>
                  </listitem>
          
                  <listitem>
                    <para>In Requirement 
                    <xref linkend="dbdoclet.50569332_67249" /> if an EEH event occurs as a
                    result of probing that fabric that results in a reset of the PE, the
                    returned PE state of 2 does not necessarily need to be checked for by the
                    software on return from the call. The case where this occurs is expected
                    to be rare, and probably signals a non-transient error. In this case the
                    software can continue on with the recovery phase of the EEH processing,
                    and will eventually hit the same event on further processing.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
        </variablelist>
        
      </section>

    </section>
    
    <section>
      <title>Bridged-I/O EEH Support Option</title>
      
      <para>The Bridged-I/O EEH Support Option provides RTAS calls for
      restoring the boot time configuration of EEH error domains that contain
      multiple IOAs or multi-function IOAs (for example, mult-function I/O
      cards which are constructed by placing multiple IOAs beneath a PCI to PCI
      bridge or PCI Express switch). During EEH recovery, the IOA is subject to
      a full hardware reset. These calls recreate any configuration changes,
      from full hardware reset, that the firmware normally makes during
      platform boot prior to turning the IOA over to the client program plus
      any subsequent changes made via ibm,change-msi. Once these calls restore
      the IOA initial configuration plus interrupts changes, it is the
      responsibility of the device driver, as part of its EEH recover
      procedure, to finish the configuration restoration with any non
      interrupts changes it makes to the IOA.</para>
      <para>Bridge types supported by these calls include PCI to PCI bridges
      (for example, a PCI to PCI bridge on an I/O plug-in card) and PCI Express
      bridges and switches.</para>
      <para>This option does not address the initialization of bridges and
      switches which are outside of all PEs. Those are the platform&#8217;s
      responsibility.</para>
      <para>If there is no supported bridge or switch at the PE configuration
      address specified by the input parameters, then these calls return a
      &#8220;success&#8221; without configuring anything, and therefore these
      calls can be made for all EEH recovery events, regardless of the type of
      I/O present. The PE configuration address (
      <emphasis>PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr</emphasis>)
      for the PE is obtained as defined in 
      <xref linkend="dbdoclet.50569332_39444" />.</para>
      <para>
      <emphasis role="bold">Software Implementation Note:</emphasis> Neither 
      <emphasis>ibm,configure-bridge</emphasis> nor 
      <emphasis>ibm,configure-pe</emphasis> restores changes to an IOA&#8217;s
      post boot configuration registers except as made through the 
      <emphasis>ibm,change-msi</emphasis> RTAS call (for example, to the point
      of being able to issue PCI memory space MMIO operations to the IOA, or
      perform DMA operations from the IOA). It is the software&#8217;s
      responsibility to restore any post boot non interrupt changes it made to
      the IOA&#8217;s PCI configuration space registers after calling one of
      these two RTAS calls.</para>
    
      <section xml:id="dbdoclet.50569332_65423">
        <title><emphasis>ibm,configure-bridge</emphasis></title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Bridged-I/O EEH Support option:</emphasis> The 
                <emphasis>ibm,configure-bridge</emphasis> call
                must implement the argument call buffer defined by 
                <xref linkend="dbdoclet.50569332_75436" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_75436">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,configure-bridge</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,configure-bridge</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>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>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>990x: Extended delay where x is a number 0-5 (see
                          Software Implementation note below)</para>
                          <para>0: Success</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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,configure-bridge</emphasis> again. However, software may
                issue the 
                <emphasis>ibm,configure-bridge</emphasis> call again either earlier or
                later than this.</para>
                <para>
                  <emphasis role="bold">Firmware Implementation Note:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>This call needs to limit the long busy to 9900-9902 with at most
                    a total of 1/5 second before the 
                    <emphasis>ibm,configure-bridge</emphasis> succeeds. Any longer delays may
                    cause subsequent hardware or application failures.</para>
                  </listitem>
          
                  <listitem>
                    <para>For hardware errors, return a 
                    <emphasis>Status</emphasis> of 0 (Success). Hardware errors are
                    subsequently discovered by further accesses to the PE and additional EEH
                    events.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The caller of 
                <emphasis>ibm,configure-bridge</emphasis> must
                provide the PE configuration address, otherwise the RTAS call returns a
                -3, &#8220;Parameter Error&#8221;.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,configure-bridge</emphasis> call
                must set up all the PCI to PCI bridges, PCI Express bridges, and PCI
                Express switches within the PE, the way they were delivered at boot time
                with any modifications made to it via RTAS calls after boot, and must do
                so with a single sequence of calls to 
                <emphasis>ibm,configure-bridge</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,configure-bridge</emphasis> call
                must only return a 
                <emphasis>Status</emphasis> of 990x if one of the following conditions is
                true:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The operation was not started.</para>
                  </listitem>
          
                  <listitem>
                    <para>Firmware is able to restart the same call for this PE even when
                    other intervening calls to 
                    <emphasis>ibm,configure-bridge</emphasis> have occurred (That is, OSs are
                    not required to serialize calls to 
                    <emphasis>ibm,configure-bridge</emphasis>).</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_31129">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>Software must
                complete all MMIO operations to the IOAs within a PE prior to calling the              
                <emphasis>ibm,configure-bridge</emphasis> RTAS call for a PE and must not
                issue new MMIO operations to the IOAs within the specified PE until after
                the RTAS call is complete.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_25668">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65423" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>On return from the 
                <emphasis>ibm,configure-bridge</emphasis> RTAS call, the platform must
                have the PE in the same EEH state (as defined by 
                <xref linkend="dbdoclet.50569332_19683" />) as when the call was made,
                except that if an error occurs in the course of probing the PCI fabric
                that requires a reset of the PE by the platform, then discontinue
                probing, return a 
                <emphasis>Status</emphasis> of 0 or 1 (as appropriate), and return the PE
                in the PE state of 2.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
        <para>
          <emphasis role="bold">Software and Platform Implementation Note:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>Given Requirements 
            <xref linkend="dbdoclet.50569332_31129" /> and 
            <xref linkend="dbdoclet.50569332_25668" />, it is permissible for the
            platform to temporarily transition the PE from a PE state of 2 to PE
            state of 4, if the call is made with a PE state of 2 but the hardware
            requires a PE state of 4 to get access to the PCI fabric. It is also
            permissible for the platform to go through several of these state changes
            during the execution of the call if there are errors that occur during
            the course of probing the PCI fabric that put the PE back into the PE
            state of 4.</para>
          </listitem>
  
          <listitem>
            <para>In Requirement 
            <xref linkend="dbdoclet.50569332_25668" /> if an EEH event occurs as a
            result of probing that fabric that results in a reset of the PE, the
            returned PE state of 2 does not necessarily need to be checked for by the
            software on return from the call. The case where this occurs is expected
            to be rare, and probably signals a non-transient error. In this case the
            software can continue on with the recovery phase of the EEH processing,
            and will eventually hit the same event on further processing.</para>
          </listitem>
        </orderedlist>		      
        
      </section>
      
      <section xml:id="dbdoclet.50569332_45262">
        <title><emphasis>ibm,configure-pe</emphasis></title>
        <para>This call has about the same semantics as the 
        <emphasis>ibm,configure-bridge</emphasis> RTAS call, except that
        it:</para>
  
        <orderedlist>		      
          <listitem>
            <para>Has the additional semantics of bypassing the configuration
            process if the PE has previously not been reset by the platform as a
            result of entering the EEH Stopped State.</para>
          </listitem>
  
          <listitem>
            <para>Configures all the configurations spaces within the PE,
            including those of the endpoint devices within the PE (see Requirement 
            <xref linkend="dbdoclet.50569332_22782" />).</para>
          </listitem>
        </orderedlist>		      
  
        <para>Thus, this RTAS call can be made at the beginning of any EEH
        processing.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Bridged-I/O EEH Support option:</emphasis> The 
                <emphasis>ibm,configure-pe</emphasis> call must implement the argument
                call buffer defined by 
                <xref linkend="dbdoclet.50569332_13087" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_13087">
                  <title>Argument Call Buffer 
                  <emphasis>ibm,configure-pe</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">
                          <para>In</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Token</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>Token for 
                          <emphasis>ibm,configure-pe</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>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>Out</para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis>Status</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>990x: Extended delay where x is a number 0-5 (see
                          Software Implementation note below)</para>
                          <para>0: Success</para>
                          <para>-3: Parameter Error</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                <emphasis role="bold">Software Implementation Note:</emphasis> 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,configure-pe</emphasis> again. However, software may issue
                the 
                <emphasis>ibm,configure-pe</emphasis> call again either earlier or later
                than this.</para>
                <para>
                  <emphasis role="bold">Firmware Implementation Note:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>This call needs to limit the long busy to 9900-9902 with at most
                    a total of 1/5 second before the 
                    <emphasis>ibm,configure-pe</emphasis> succeeds. Any longer delays may
                    cause subsequent hardware or application failures.</para>
                  </listitem>
          
                  <listitem>
                    <para>For hardware errors, return a 
                    <emphasis>Status</emphasis> of 0 (Success). Hardware errors are
                    subsequently discovered by further accesses to the PE and additional EEH
                    events.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The caller of 
                <emphasis>ibm,configure-pe</emphasis> must provide the PE configuration
                address, otherwise the RTAS call returns a -3, &#8220;Parameter
                Error&#8221;.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_22782">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>If the specified
                PE has been configured after the last platform or OS initiated reset to
                the specified PE with 
                <emphasis>ibm,configure-connector</emphasis>,
                <emphasis>ibm,configure-bridge</emphasis>, or 
                <emphasis>ibm,configure-pe</emphasis>, then the call must return with a 
                <emphasis>Status</emphasis> of 0 (Success) without doing any bridge or
                switch configuration, otherwise the call must set up the configuration
                spaces of all the PCI to PCI bridges, PCI Express bridges, PCI Express
                switches, and endpoint functions within the PE, the way they were
                delivered at boot time except with all sticky error bits left intact, any
                changes made by calls to ibm,change-msi retained, and must do so with a
                single sequence of calls to 
                <emphasis>ibm,configure-pe</emphasis>.</para>
                <para>
                  <emphasis role="bold">Software Implementation Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>The configuration of endpoint functions (the &#8220;and endpoint
                    functions&#8221; part) in Requirement 
                    <xref linkend="dbdoclet.50569332_22782" /> was added to the architecture
                    after the firmware without that functionality in the 
                    <emphasis>ibm,configure-pe</emphasis> RTAS call was shipping. Therefore,
                    any device driver that might run legacy implementations needs to be
                    prepared to restore all endpoint function config spaces, since the 
                    <emphasis>ibm,configure-pe</emphasis> RTAS call might not.</para>
                  </listitem>
          
                  <listitem>
                    <para>The <emphasis>ibm,configure-pe</emphasis> RTAS call does not restore
                    non-interrupts configuration space changes that were made after boot
                    (that is, under direction of the device driver or OS). Therefore, use of
                    the 
                    <emphasis>ibm,configure-pe</emphasis> RTAS call does not absolve the
                    device driver or OS from the restoration of non-interrupts the PCI
                    configuration space for changes that were made to the configuration space
                    after boot (see Requirement 
                    <xref linkend="LoPAR.Platform" />).</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para>The <emphasis>ibm,configure-pe</emphasis> call must only return a 
                <emphasis>Status</emphasis> of 990x if one of the following conditions is
                true:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The operation was not started.</para>
                  </listitem>
          
                  <listitem>
                    <para>Firmware is able to restart the same call for this PE even when
                    other intervening calls to 
                    <emphasis>ibm,configure-pe</emphasis> have occurred (That is, OSs are not
                    required to serialize calls to 
                    <emphasis>ibm,configure-pe</emphasis>).</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_95449">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para>Software must
                complete all MMIO operations to the IOAs within a PE prior to calling the
                <emphasis>ibm,configure-pe</emphasis> RTAS call for a PE and must not
                issue new MMIO operations to the IOAs within the specified PE until after
                the RTAS call is complete.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_90530">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45262" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para>On return from the 
                <emphasis>ibm,configure-pe</emphasis> RTAS call, the platform must have
                the PE in the same EEH state (as defined by 
                <xref linkend="dbdoclet.50569332_19683" />) as when the call was made,
                except that if an error occurs in the course of probing the PCI fabric
                that requires a reset of the PE by the platform, then discontinue
                probing, return a 
                <emphasis>Status</emphasis> of 0 or 1 (as appropriate), and return the PE
                in the PE state of 2.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
        <para>
          <emphasis role="bold">Software and Platform Implementation Note:</emphasis>
        </para>
        
        <orderedlist>		      
          <listitem>
            <para>Given Requirements 
            <xref linkend="dbdoclet.50569332_95449" /> and 
            <xref linkend="dbdoclet.50569332_90530" />, it is permissible for the
            platform to temporarily transition the PE from a PE state of 2 to PE
            state of 4, if the call is made with a PE state of 2 but the hardware
            requires a PE state of 4 to get access to the PCI fabric. It is also
            permissible for the platform to go through several of these state changes
            during the execution of the call if there are errors that occur during
            the course of probing the PCI fabric that put the PE back into the PE
            state of 2.</para>
          </listitem>
  
          <listitem>
            <para>In Requirement 
            <xref linkend="dbdoclet.50569332_90530" /> if an EEH event occurs as a
            result of probing that fabric that results in a reset of the PE, the
            returned PE state of 2 does not necessarily need to be checked for by the
            software on return from the call. The case where this occurs is expected
            to be rare, and probably signals a non-transient error. In this case the
            software can continue on with the recovery phase of the EEH processing,
            and will eventually hit the same event on further processing.</para>
          </listitem>
        </orderedlist>		      
        
      </section>

    </section>
    
    <section xml:id="dbdoclet.50569332_22302">
      <title>Error Injection Option</title>
      
      <para>The Error Injection option (ERRINJCT) allows testing software to
      check out the OS&#8217;s error paths. This architecture defines the
      following abstract error categories:</para>
      <para>Fatal: Platform Architectural state has been corrupted to an
      unknown extent. Further valid processing is not possible.</para>
      <para>Recovered Random Event: The Central Electronics Complex (CEC)
      experienced an anomaly. However, platform architectural state has been
      preserved/restored. The OS should log the event and continue
      processing.</para>
      <para>Recovered Special Event: The CEC has experienced a statistically
      significant anomaly. While platform architectural state has been
      preserved/restored, the OS should log the event and discontinue the use
      of this processor as soon as possible to avoid a fatal situation.</para>
      <para>Corrupted Page: The System Memory page (Up to 4 KB) contains
      uncorrectable errors. The OS should log the event and avoid accessing
      this page in the future. The OS recovery is possible given that it can
      either recover the page from backing storage or isolate the error from
      unaffected processes.</para>
      <para>Corrupted SLB: The processor&#8217;s Segment Look-aside Buffer is
      corrupted. The OS should log the event and can recover if it can
      repopulate the SLB from internal tables.</para>
      <para>Translator Failure: The processor&#8217;s virtual to real
      translation hardware has failed. The processor&#8217;s architectural
      state has been preserved in System Memory. The OS may be able to continue
      the failed processor&#8217;s program and log the event on an alternate
      processor in the future.</para>
      <para>IOA Bus Error An error has occurred on the I/O bus on which an I/O
      Adapter (IOA) is attached. IOA or Device driver recovery from the error
      is possible if the error is such that it is reported to the IOA. Device
      driver recovery of the IOA&#8217;s operations is possible when the error
      is not reported to the IOA, if the EEH option is implemented and
      enabled.</para>
      <para>The ERRINJCT option RTAS call performs a platform dependent
      accurate simulation of the abstract error requested. In some cases, the
      platform hardware actually injects an error into the hardware. In others
      cases, the platform may simply report the anomaly without generating an
      error. Additionally, the ERRINJCT option provides access to platform
      specific error injection logic for the benefit of platform aware test
      software.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> RTAS must implement the 
              <emphasis>ibm,open-errinjct</emphasis> call
              using the argument buffer defined by 
              <xref linkend="dbdoclet.50569332_92988" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_92988">
                <title>Argument Call Buffer 
                <emphasis>ibm,open-errinjct</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">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for 
                        <emphasis>ibm,open-errinjct</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>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1">
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Open Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>If 
                        <emphasis>Status</emphasis> is 0, then use this Open Token for
                        corresponding 
                        <emphasis>ibm,errinjct</emphasis> and 
                        <emphasis>ibm,close-errinjct</emphasis> calls</para>
                      </entry>
                    </row>
                    <row>
                      <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</para>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy, try again later</para>
                        <para>-4: Already open</para>
                        <para>-5: PCI Error Injection is not enabled (not
                        available)</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 with the same parameters. However,
              software may issue the call again either earlier or later than
              this.</para>
              <para>
              <emphasis role="bold">Architecture Note:</emphasis> The output buffer is intentionally
              reversed from what it should be, according to Requirement 
              <xref linkend="dbdoclet.50569332_94431" /> (that is, 
              <emphasis>Status</emphasis> not first output), due to code that was
              implemented and shipped as defined, above.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> On successful completion of
              the 
              <emphasis>ibm,open-errinjct call</emphasis>, Firmware must return an Open
              Token which uniquely identifies the caller on following 
              <emphasis>ibm,close-errinjct</emphasis> and 
              <emphasis>ibm,errinjct</emphasis> calls (Firmware may also need to keep
              around other information about the caller that uniquely identifies the
              caller when correlated with the Open Token) and must allocate the
              ERRINJCT facilities to this caller until this same user calls 
              <emphasis>ibm,close-errinjct</emphasis>.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> If the ERRINJCT facility has
              been previously opened, a call to 
              <emphasis>ibm,open-errinjct call</emphasis>, must return a -4.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> RTAS must implement the 
              <emphasis>ibm,close-errinjct</emphasis> call
              using the argument buffer defined by 
              <xref linkend="dbdoclet.50569332_41203" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_41203">
                <title>Argument Call Buffer 
                <emphasis>ibm,close-errinjct</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">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for 
                        <emphasis>ibm,close-errinjct</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>Open Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Open Token that was returned on the corresponding 
                        <emphasis>ibm,open-errinjct</emphasis> calls</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <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</para>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy, try again later</para>
                        <para>-4: Close Error (User is not the one that opened the
                        ERRINJCT facility or facility not open)</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 with the same parameters. However,
              software may issue the call again either earlier or later than
              this.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> If the ERRINJCT facility is
              not open or was not previously allocated to the user via an 
              <emphasis>ibm,open-errinjct</emphasis> call (that is, the Open Token along
              with any other pertinent data does not correspond with the user that
              opened the facility via the 
              <emphasis>ibm,open-errinjct</emphasis> call), then a call to 
              <emphasis>ibm,close-errinjct call</emphasis>, must return a -4 and the
              facility must remain open for use by the user that originally opened the
              facility.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> RTAS must implement the 
              <emphasis>ibm,errinjct</emphasis> call
              using the argument buffer defined by 
              <xref linkend="dbdoclet.50569332_12614" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_12614">
                <title>Argument Call Buffer 
                <emphasis>ibm,errinjct</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">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for 
                        <emphasis>ibm,errinjct</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>Errinjct Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for the specific error injection class see
                        Requirement 
                        <xref linkend="dbdoclet.50569332_11411" /></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Open Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>The Open Token that was returned on the corresponding 
                        <emphasis>ibm,open-errinjct</emphasis> call</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Working Buffer</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real address of a 1 KB buffer on a 1 KB boundary</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Out</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Status</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>990x: Extended delay where x is a number 0-5</para>
                        <para>0: Success</para>
                        <para>-1: Hardware Error</para>
                        <para>-2: Busy, try again later</para>
                        <para>-3 Argument Error (Optional)</para>
                        <para>-4: Call Error (User is not the one that opened the
                        ERRINJCT facility or facility not open)</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 with the same parameters. However,
              software may issue the call again either earlier or later than
              this.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> If the ERRINJCT facility is
              not open or was not previously allocated to the user via an 
              <emphasis>ibm,open-errinjct</emphasis> call (that is, the Open Token along
              with any other pertinent data does not correspond with the user that
              opened the facility via the 
              <emphasis>ibm,open-errinjct</emphasis> call), then a call to 
              <emphasis>ibm,errinjct call</emphasis>, must return a -4 and the facility
              must remain open for use by the user that originally opened the
              facility.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_11411">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis>
              The platform must include the 
              <emphasis role="bold"><literal>&#8220;ibm,errinjct-tokens&#8221;</literal></emphasis> property as defined
              below in the 
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node (see 
              <xref linkend="LoPAR.DeviceTree" />) of the OF device tree with a
              specification for each implemented error injection class.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> The errinjct-token-names
              must be taken from the list provided in 
              <xref linkend="dbdoclet.50569332_35100" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_35100.1">
                <title>Errinjct-token-names</title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Errinjct-token-name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Errinjct function</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>fatal</para>
                      </entry>
                      <entry>
                        <para>Simulate a platform fatal error.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>recovered-random-event</para>
                      </entry>
                      <entry>
                        <para>Simulate a recovered random event</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>recovered-special-event</para>
                      </entry>
                      <entry>
                        <para>Simulate a recovered special (statistically significant)
                        event</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-page</para>
                      </entry>
                      <entry>
                        <para>Corrupt the specified location (and potentially
                        surrounding locations up to the containing page)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-slb</para>
                      </entry>
                      <entry>
                        <para>Corrupt the SLB entry associated with a specific
                        effective address.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>translator-failure</para>
                      </entry>
                      <entry>
                        <para>Simulate a translator failure.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>ioa-bus-error</para>
                      </entry>
                      <entry>
                        <para>Simulate an error on an IOA bus - 32 bit address
                        specification only.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>ioa-bus-error-64</para>
                      </entry>
                      <entry>
                        <para>Simulate an error on an IOA bus - 64 bit address
                        specification.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>platform-specific</para>
                      </entry>
                      <entry>
                        <para>Request the firmware perform a platform specific error
                        injection.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-dcache-start</para>
                      </entry>
                      <entry>
                        <para>Start causing a L1 data cache error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-dcache-end</para>
                      </entry>
                      <entry>
                        <para>Stop causing a L1 data cache error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-icache-start</para>
                      </entry>
                      <entry>
                        <para>Start causing an instruction cache error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-icache-end</para>
                      </entry>
                      <entry>
                        <para>Stop causing an instruction cache error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-tlb-start</para>
                      </entry>
                      <entry>
                        <para>Start corrupting TLB</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-tlb-end</para>
                      </entry>
                      <entry>
                        <para>Stop corrupting TLB</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>upstream-IO-error</para>
                      </entry>
                      <entry>
                        <para>Inject I/O error above the IOA</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> For the errinjct-tokens
              implemented RTAS must use the work buffer format specified in 
              <xref linkend="dbdoclet.50569332_33582" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_33582">
                <title>Errinjct Work Buffer Formats</title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Errinjct-token-name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Errinjct work buffer format</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>fatal</para>
                      </entry>
                      <entry>
                        <para>Undefined</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>recovered-random-event</para>
                      </entry>
                      <entry>
                        <para>Undefined</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>recovered-special-event</para>
                      </entry>
                      <entry>
                        <para>&#8220;1&#8221; for a non-persistent cpu recoverable
                        error</para>
                        <para>&#8220;2&#8221; for a persistent CPU recoverable
                        error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-page</para>
                      </entry>
                      <entry>
                        <para>The first cell contains the upper 32 bits of the real
                        address to corrupt. The second cell contains the lower 32 bits
                        of the real address to corrupt.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-slb</para>
                      </entry>
                      <entry>
                        <para>The first cell contains the effective address associated
                        with the SLB entry to corrupt</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>translator-failure</para>
                      </entry>
                      <entry>
                        <para>Undefined</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>ioa-bus-error</para>
                      </entry>
                      <entry>
                        <para>The first word contains I/O bus address, word aligned, at
                        which to inject the error. The second word is a mask used to
                        mask off up to 24 of the least significant bits of the address
                        which are not to be used in the comparison of address for error
                        injection (a 0 in a bit position masks off the bit, a 1 in the
                        bit position enables the bit to be used in the compare). The
                        third word is the config_addr on the bus which is to receive
                        the injected error. The fourth word is the 
                        <emphasis>PHB_Unit_ID_Hi</emphasis> of the PHB that corresponds
                        to the 
                        <emphasis>config_addr</emphasis>. The fifth word is the 
                        <emphasis>PHB_Unit_ID_Low</emphasis> of the PHB that corresponds
                        to the 
                        <emphasis>config_addr</emphasis>. The sixth word defines the
                        specifics of when and what to inject, as follows:</para>
        
                        <para>See 
                        <xref linkend="dbdoclet.50569332_63533" /> for values 0 through
                        19.</para>
                        <para>20: (Optional) Disable PCI error injection for the
                        specified bus</para>
                        <para>21: Obtain current error inject values. When RTAS returns
                        SUCCESS in the 
                        <emphasis>Status</emphasis> field the work buffer field values
                        are populated with the current error injected.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>ioa-bus-error-64</para>
                      </entry>
                      <entry>
                        <para>The first and second words contain the I/O bus address,
                        double word aligned, at which to inject the error. The third
                        and fourth words are a mask used to mask off up to 64 of the
                        least significant bits of the address which are not to be used
                        in the comparison of address for error injection (a 0 in a bit
                        position masks off the bit, a 1 in the bit position enables the
                        bit to be used in the compare). The fifth word is the
                        config_addr of an IOA on the bus which is to receive the
                        injected error. The sixth word is the 
                        <emphasis>PHB_Unit_ID_Hi</emphasis> of the PHB that corresponds
                        to the 
                        <emphasis>config_addr</emphasis>. The seventh word is the 
                        <emphasis>PHB_Unit_ID_Low</emphasis> of the PHB that corresponds
                        to the 
                        <emphasis>config_addr.</emphasis> The eighth word defines the
                        specifics of when and what to inject, as follows:</para>
        
                        <para>See 
                        <xref linkend="dbdoclet.50569332_63533" /> for values 0 through
                        19.</para>
                        <para>20: (Optional) Disable PCI error injection for the
                        specified bus</para>
                        <para>21: Obtain current error inject values. When RTAS returns
                        SUCCESS in the 
                        <emphasis>Status</emphasis> field the work buffer field values
                        are populated with the current error injected.
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>platform-specific</para>
                      </entry>
                      <entry>
                        <para>See platform firmware documentation (RTAS component
                        specifications) for working buffer format for any particular
                        platform.</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="0">
                        <para>corrupted-dcache-start</para>
                        <para>corrupted-dcache-end</para>
                      </entry>
                      <entry morerows="0">
                        <para>The first cell defines the specific action to
                        take:</para>
                        <para>0: Parity error</para>
                        <para>1: D-ERAT parity error</para>
                        <para>2: tag parity error</para>
                        <para>The second cell defines the nature of the error:</para>
                        <para>0: single</para>
                        <para>1: solid</para>
                        <para>2: hang</para>
                        <para>Supported injection modes are hardware specific and all
                        modes may not be supported on all hardware. The first supported
                        injection mode in the above list will be used if an unsupported
                        mode is specified (that is, first single, then solid, then
                        hang-pulse). If none of the above modes are available, then the
                        injection option most similar to single in functionality will
                        be used.</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="0">
                        <para>corrupted-icache-start</para>
                        <para>corrupted-icache-end</para>
                      </entry>
                      <entry morerows="0">
                        <para>The first cell defines the specific action to
                        take:</para>
                        <para>0: parity error</para>
                        <para>1: I-ERAT parity error</para>
                        <para>2: cache directory 0 parity error</para>
                        <para>3: cache directory 1 parity error</para>
                        <para>The second cell defines the nature of the error:</para>
                        <para>0: single</para>
                        <para>1: solid</para>
                        <para>2: hang</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>corrupted-tlb-start</para>
                        <para>corrupted-tlb-end</para>
                      </entry>
                      <entry>
                        <para>The first cell defines the nature of the error:</para>
                        <para>0: single</para>
                        <para>1: solid</para>
                        <para>2: hang</para>
                        <para>Supported injection modes are hardware specific and all
                        modes may not be supported on all hardware. The first supported
                        injection mode in the above list will be used if an unsupported
                        mode is specified (that is, first single, then solid, then
                        hang-pulse). If none of the above modes are available, then the
                        injection option most similar to single in functionality will
                        be used.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <para>
              <emphasis role="bold">Programming Note:</emphasis> Options having a
              &#8220;-start&#8221; and corresponding &#8220;-end&#8221; must be called
              in pairs on the same processor. The corresponding &#8220;-end&#8221;
              option should be called after the injected error has been noticed and
              processed by the caller. On the same processor, other error inject
              options should not be called between a &#8220;-start&#8221; and
              &#8220;-end&#8221; sequence. However, it is possible to inject the same
              type of error multiple times by calling &#8220;-start&#8221; on that CPU
              as long as the &#8220;nature of error&#8221; is &#8220;single&#8221;. The
              buffer contents should be the same for a &#8220;-start&#8221; and
              corresponding &#8220;-end&#8221;. While not recommended -end can be
              replaced with a call to 
              <emphasis>ibm,close-errinjct</emphasis>, but improper cleanup the machine
              may result, with the machine left in an unknown state.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option:</emphasis> If the platform 
              notifies the OS of a specific CEC error using the machine check interrupt in 
              response to an 
              <emphasis>ibm,errinjct</emphasis> RTAS call, the platform must do so only
              when the processor&#8217;s MSR<subscript>RI</subscript> bit is active, unless said error is fatal or
              involves accessing a storage location that has itself been corrupted or
              is accessed through a corrupted SLB entry.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option with the LPAR
              option:</emphasis> Hypervisor RTAS must allow a partition to only corrupt
              its own memory pages.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option with the LPAR
              option:</emphasis> Hypervisor RTAS must allow a partition to inject IOA
              bus errors only if all of the following are true:</para>
              
              <orderedlist numeration="loweralpha">		      
                <listitem>
                  <para>The IOA bus is not shared with other partitions.</para>
                </listitem>
        
                <listitem>
                  <para>The EEH option is implemented and enabled for the bus on which
                  the error injection is requested.</para>
                </listitem>
              </orderedlist>		      
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the ERRINJCT option with the LPAR option:</emphasis> The
              platform must allow at most one partition to issue platform-specific
              errinjct calls.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must either
              implement actual hardware error injection with these interfaces, or must
              fabricate appropriate partition behavior (machine check, error logs,
              etc.) as if the hardware error had happened.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Multi-threading Processor 
              option:</emphasis> All threads
              on the processor on which the error is injected must be prepared to
              handle the error.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Error Injection option:</emphasis> The software using
              the 
              <emphasis>ibm,errinjct</emphasis> call must be prepared to receive a -3
              for non-implemented errinjct work buffer formats.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_22302" 
          xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
            <listitem>
              <para><emphasis>For the</emphasis>
              <emphasis>ioa-bus-error</emphasis>
              <emphasis>and</emphasis>
              <emphasis>ioa-bus-error-64</emphasis>
              <emphasis role="bold">functions of the ERRINJCT option:</emphasis> For each 
              <emphasis>ibm,errinjct</emphasis> RTAS call invocation, the platform must
              inject the error specified in the 
              <emphasis>working buffer</emphasis> at most once.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_63533">
                <title>Semantics for 
                <emphasis>ioa-bus-error</emphasis>
                <emphasis>ioa-bus-error</emphasis> Sixth Word and 
                <emphasis>ioa-bus-error-64</emphasis> Eighth Word Values 0-19</title>
                <tgroup cols="5">
                  <colspec colname="c1" colwidth="20*" />
                  <colspec colname="c2" colwidth="20*" />
                  <colspec colname="c3" colwidth="20*" />
                  <colspec colname="c4" colwidth="20*" />
                  <colspec colname="c5" colwidth="20*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Operation</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Address Space</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Cell Value</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Conventional PCIPCI-X Mode 1PCI-X Mode
                          2</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">PCI Express</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry morerows="5">
                        <para>
                          <emphasis>Load</emphasis>
                        </para>
                      </entry>
                      <entry morerows="1">
                        <para>PCI Memory</para>
                      </entry>
                      <entry>
                        <para>0</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                      <entry morerows="5">
                        <para>Inject a TLP ECRC Error
                        <footnote xml:id="pgfId-1214143">
                          <para>For PHB implementations that do not allow injection of
                          a TLP ECRC error into the request, or for the case where the
                          injection would be in violation of Requirement 
                          <xref linkend="LoPAR.Platform" /> due to the hardware
                          configuration, the platform should emulate the error by
                          setting the appropriate error state in the PHB when EEH is
                          enabled.</para>
                        </footnote></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>1</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1">
                        <para>PCI I/O</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>3</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1">
                        <para>PCI Configuration</para>
                      </entry>
                      <entry>
                        <para>4</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>5</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="5">
                        <para>
                          <emphasis>Store</emphasis>
                        </para>
                      </entry>
                      <entry morerows="1">
                        <para>PCI Memory</para>
                      </entry>
                      <entry>
                        <para>6</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                      <entry morerows="5">
                        <para>Inject a TLP ECRC Error (optional)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>7</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1">
                        <para>PCI I/O</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>9</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="1">
                        <para>PCI Configuration</para>
                      </entry>
                      <entry>
                        <para>10</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>11</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="3">
                        <para>DMA read</para>
                      </entry>
                      <entry morerows="3">
                        <para>PCI Memory</para>
                      </entry>
                      <entry>
                        <para>12</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                      <entry morerows="1">
                        <para>Inject a TLP ECRC Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>13</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>14</para>
                      </entry>
                      <entry>
                        <para>Inject a Master Abort (no response to IOA) Error</para>
                      </entry>
                      <entry>
                        <para>--</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>15</para>
                      </entry>
                      <entry>
                        <para>Inject a Target Abort</para>
                      </entry>
                      <entry>
                        <para>Inject a Completer Abort or Unsupported Request
                        <footnote xml:id="pgfId-1214297">
                          <para>Inject the error that is injected on a TCE Page
                          Fault.</para>
                        </footnote></para>
                      </entry>
                    </row>
                    <row>
                      <entry morerows="3">
                        <para>DMA write</para>
                      </entry>
                      <entry morerows="3">
                        <para>PCI Memory</para>
                      </entry>
                      <entry>
                        <para>16</para>
                      </entry>
                      <entry>
                        <para>Inject an Address Parity Error</para>
                      </entry>
                      <entry morerows="1">
                        <para>Inject a TLP ECRC Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>17</para>
                      </entry>
                      <entry>
                        <para>Inject a Data Parity Error</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>18</para>
                      </entry>
                      <entry>
                        <para>Inject a Master Abort (no response to IOA) Error</para>
                      </entry>
                      <entry>
                        <para>--</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>19</para>
                      </entry>
                      <entry>
                        <para>Inject a Target Abort</para>
                      </entry>
                      <entry>
                        <para>Not Applicable</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
      </variablelist>

              
      <para>
        <emphasis role="bold">Platform Implementation Notes:</emphasis>
      </para>
      
      <itemizedlist>		      
        <listitem>
          <para>Platforms that implement LPAR normally do not allow any partition
          to be configured to perform platform-specific errinjct calls since they
          are capable of crashing the entire complex. However, the should provide
          special hidden overrides for laboratory testing purposes.</para>
        </listitem>
      </itemizedlist>		      
        
      <para>
        <emphasis role="bold">Software and Firmware Implementation Notes:</emphasis>
      </para>

      <itemizedlist>		      
        <listitem>
          <para>When a call to 
          <emphasis>ibm,errinjct</emphasis> results in an error injected into a
          processor, then the error is injected on the same processor as the one
          that called the 
          <emphasis>ibm,errinjct</emphasis> RTAS call, not the processor that called
          the 
          <emphasis>ibm,open-errinjct</emphasis>. The OS could call 
          <emphasis>ibm,open-errinjct</emphasis>, 
          <emphasis>ibm,errinjct</emphasis>, and 
          <emphasis>ibm,close-errinjct</emphasis> from three different
          processors.</para>
        </listitem>
        
        <listitem>
          <para>For usability reasons, the 
          <emphasis>ibm,close-errinjct</emphasis> RTAS call should do a reasonable
          amount of cleanup; turning off error injection where it can. However,
          since the ERRINJCT option is intended for internal use (that is, not
          intended to be productized) and since software is allowed to basically
          set unlimited error injections between the calls to 
          <emphasis>ibm,open-errinjct</emphasis> and 
          <emphasis>ibm,close-errinjct</emphasis>, the firmware may vary by
          implementation as to what is cleaned up and what is not. An example of
          something that might be very difficult to clean up is injection of memory
          errors. Something that might be easier is to turn off the error injection
          in all bridges to which the caller has access. Users of the ERRINJCT
          option should consult the implementation documentation for a particular
          platform to learn about the level of cleanup that is done in the 
          <emphasis>ibm,close-errinjct</emphasis> call for that implementation. In
          the severe case, a reboot may even be necessary after the 
          <emphasis>ibm,close-errinjct</emphasis> in order to clear the error. In
          other cases it may be possible for the caller to partially disable an
          error that it has set by setting a benign error (for example, in the PCI
          error injection case, by setting the error injection for a bus that was
          previously set to inject an error to an address that will never occur to
          that IOA).</para>
        </listitem>
        
        <listitem>
          <para>Test developers are encouraged not to extensively use the
          platform-specific option to this function. In general, platform-specific
          implementation options are not carried forward to new platforms.</para>
        </listitem>
      </itemizedlist>		      
      
    </section>
    
    <section xml:id="dbdoclet.50569332_12478">
      <title>Firmware Assisted Non-Maskable Interrupts Option
      (FWNMI)</title>
      
      <para>The FWNMI option provides firmware support for System Reset
      interrupts and platform dependent error recovery for recoverable machine
      checks. The firmware gets control on a non-maskable interrupt (NMI),
      analyses the condition, and, if the processor was not running inside the
      hypervisor, reports its findings to the OS. The OS registers system reset
      and machine check handlers by issuing either the 
      <emphasis>ibm,nmi-</emphasis> register or 
      <emphasis>ibm,nmi-</emphasis> register-2 RTAS call. In addition, with
      these calls the OS permanently relinquishes to firmware the Machine State
      Register&#8217;s Machine Check Enable bit, the two hundred fifty six
      (256) bytes of the System Reset Interrupt vector starting at real
      location 0x100, the two hundred fifty six (256) bytes of the Machine
      Check Interrupt vector starting at real location 0x200, as well as the
      storage page starting at real location 0x7000. The RTAS firmware records
      the entry points of the OS notification routines to call to report the
      results of the firmware&#8217;s analysis and any attempted recovery
      should the hardware signal a machine check or system reset interrupt. The
      results of an error analysis are reported via a standard error log
      structure as defined in 
      <xref linkend="LoPAR.Error" />. The storage containing the
      error log structure is subsequently released back to firmware use by the
      OS after it has completed its event handling by the issuance, from the
      interrupted processor, of the 
      <emphasis>ibm,nmi-interlock</emphasis> RTAS call. Multiple processors of
      the same OS image may experience fatal events at, or about, the same
      time. The first processor to enter the machine check handling firmware
      reports the fatal error. Subsequent processors serialize waiting for the
      first processor to issue the 
      <emphasis>ibm,nmi-interlock</emphasis> call. These subsequent processors
      report &#8220;fatal error previously reported&#8221;. If, after the
      firmware makes a Machine Check call back, and before the OS issues the 
      <emphasis>ibm,nmi-interlock</emphasis> call, the same processor that is
      currently holding the storage containing the error log structure receives
      another Machine Check NMI, the firmware has no choice but to declare the
      condition fatal, log the result and execute the partition&#8217;s reboot
      policy.</para>
      <para>When the OS gets control after a machine check, at its registered
      machine check notification routine, all architected processor registers
      have been restored to the values they contained when the firmware was
      notified of the interrupt, except for register R3 which contains a real
      address that points to a 16 byte structure. The first 8 bytes of this
      area contains the original contents of R3 and the second 8 bytes contains
      the fixed portion of the standard error log structure. If firmware is
      able to immediately make a repair determination, the fixed portion
      indicates that an additional variable part is present and follows the
      fixed part per the standard error log structure. For some other errors,
      the determination of the repair action is delayed, and the firmware
      reports these determinations asynchronously to handling the machine
      check. The repair action log is queued in the NVRAM and is reported
      either in a subsequent 
      <emphasis>event-scan</emphasis> if the OS image remains operational, or on
      a subsequent boot. In no case, does the OS call 
      <emphasis>check-exception</emphasis> in its machine check notification
      routine.</para>
      <para>The difference between 
      <emphasis>ibm,nmi-</emphasis> register and 
      <emphasis>ibm,nmi-</emphasis> register-2 is that 
      <emphasis>ibm,nmi-</emphasis> register allocates the error reporting
      structure in RTAS space while 
      <emphasis>ibm,nmi-</emphasis> register-2 places the error reporting
      structure in real page 7. New OS designs should use 
      <emphasis>ibm,nmi-</emphasis> register since support for 
      <emphasis>ibm,nmi-</emphasis> register-2 will be terminated at some future
      date.</para>
      <para>As with all first level interrupt service routines, the SPRG-2
      register is used to save the state of one general purpose register while
      the processor computes the location of its state save area.</para>
      <para>
      <emphasis role="bold">Implementation Note:</emphasis> An acceptable non-LPAR firmware
      implementation for the NMI check handlers saves one register in an
      SPRG-2. Then, using the processor number register, determines an offset
      into a page 7 table of addresses to the start of a per processor RTAS
      save area (only need a single register saved per processor), and acquires
      a lock located in page 7 to serialize the use of the RTAS state save area
      among potentially competing processors. The MSR<subscript>ME</subscript> 
      bit then prevents single processor Machine Check
      stacking in the interval between the Machine Check call back and the 
      <emphasis>ibm,nmi-interlock</emphasis> call. LPAR implementations should
      minimize potential effects to innocent partitions due to Machine Check
      Interrupts affecting other partitions.</para>
      <para>If the NMI was taken inside the hypervisor, then, if the firmware
      determines that the condition is recoverable, the hypervisor recovery
      routine is invoked. If the condition is not recoverable, hypervisor clean
      up routines establish a safe state and mark the hypervisor return routine
      to invoke the proper OS registered NMI routine rather than doing the
      standard hypervisor return.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>All platforms must implement the FWNMI
              option.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_64987">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis>
              The platform must include the 
              <emphasis role="bold"><literal>&#8220;ibm,nmi-register&#8221;</literal></emphasis>
              RTAS function property name in the OF 
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_79743">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis>
              The platform must include the 
              <emphasis role="bold"><literal>&#8220;ibm,nmi-register-2&#8221;</literal></emphasis>
              RTAS function property name in the OF 
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node if the platform requires support from
              interim OS versions.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> RTAS must implement the 
              <emphasis>ibm,nmi-register</emphasis> and/or 
              <emphasis>ibm,nmi-register-2,</emphasis> calls as appropriate per
              Requirements 
              <xref linkend="dbdoclet.50569332_64987" /> and 
              <xref linkend="dbdoclet.50569332_79743" /> using the argument buffer
              defined by 
              <xref linkend="dbdoclet.50569332_32304" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_32304">
                <title>Argument Call Buffer
                <emphasis>ibm,nmi-register or ibm,nmi-register-2</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">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for 
                        <emphasis>ibm,nmi-register or nmi-register-2</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number of Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number of Outputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>System Reset Notification Routine</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real/Logical address of OS routine to call on a System
                        Reset (in the first 32 MB of memory).</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Machine Check a</emphasis>
                        </para>
                        <para>
                          <emphasis>Notification Routine</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Real/Logical address of OS routine to call on a Machine
                        Check (in the first 32 MB of memory).</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_12478" 
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> Once the 
              OS has registered for
              NMI notification, it must not change the contents of the two hundred
              fifty six (256) bytes of the NMI interrupt vectors at real locations
              0x100 or 0x200 or the memory page starting at real location
              0x7000.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry xml:id="dbdoclet.50569332_61152">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis>
              The Real/Logical
              address of the registered OS Machine Check and System Reset routines must
              be in the first 32 MB of the OS&#8217;s memory address space.</para>
              <para>
              <emphasis role="bold">Software Implementation Note:</emphasis> Requirement 
              <xref linkend="dbdoclet.50569332_61152" /> ensures that the registered OS
              Machine Check and System Reset routines are within the code&#8217;s
              RMA.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> If the OS registered with 
              <emphasis>ibm,nmi-register</emphasis>, firmware must not store the state
              of the processor at the time of interrupt in interrupt vectors at
              locations 0x100 or 0x200 or the memory page starting at real location
              0x7000. Firmware may use RTAS space to store such state data.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> Once the OS has registered for
              NMI notification, the platform firmware must intercept all System Reset
              Interrupts on all of the OS&#8217;s processors.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> The 
              platform firmware, for
              those intercepted System Reset interrupts which platform policy dictate
              are to be forwarded to the OS, must invoke the OS registered System Reset
              Interrupt notification point with translate off and all other architected
              processor registers restored to their state at the time of the System
              Reset.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> Once the OS has registered for
              NMI notification, the platform firmware must intercept all Machine Check
              Interrupts on all of the OS&#8217;s processors.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">or the FWNMI option:</emphasis> The platform must provide a
              mechanism for the firmware to signal a non-maskable interrupt to each
              processor in a partition.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> The platform firmware must
              analyze all intercepted Machine Check Interrupts, determine if the OS may
              safely continue using the platform, attempt to recover any corrupted
              architectural state, and report the results of the recovery attempt to
              the OS.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> If the platform firmware, on
              analyzing an intercepted Machine Check Interrupt, determines that the OS
              may safely continue using the platform, it must invoke the OS registered
              Machine Check Interrupt notification point with translate off but all
              other architected processor registers restored to their state at the time
              of the Machine Check except that General Purpose Register (GPR) R3
              contains the real address of a 16 byte memory buffer containing the
              original contents of GPR R3 in the first 8 bytes and the RTAS Error Log
              (fixed part) (per 
              <xref linkend="LoPAR.Error" />) in the second 8 bytes.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> The maximum time for the
              platform&#8217;s processing of a non-fatal machine check interrupt must
              be on the order of that taken by the 
              <emphasis>check-exception</emphasis> critical call.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> Once the firmware has reported
              a &#8220;fatal&#8221; machine check event to an OS image it must only
              report &#8220;fatal error previously reported&#8221; (see 
              <xref linkend="LoPAR.Error" />) in response to machine checks
              on any processor belonging to that image.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> If the platform firmware, on
              analyzing an intercepted Machine Check Interrupt, determines that the OS
              may not safely continue using the processor (for example a check stop
              will certainly result), it must select one of the implementation options
              given in 
              <xref linkend="dbdoclet.50569332_42152" />.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_42152">
                <title>Unsafe Processor Recovery Options</title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <thead>
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Option Number</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Implementation Option for handling an
                          unsafe processor.</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody>
                    <row>
                      <entry>
                        <para>1</para>
                      </entry>
                      <entry>
                        <para>Invoke the registered Machine Check Interrupt
                        notification point on a spare processor which platform firmware
                        substitutes for the offending processor.</para>
                        <para>
                        <emphasis role="bold">Note:</emphasis> Firmware must adjust all interrupt
                        XIVT entries and APM registers, etc., so that the OS need not
                        be aware of the processor substitution. The VPD of the new and
                        old processors are different, the dynamic VPD collection RTAS
                        call can be used to determine the new values. Since the results
                        of this substitution are indicated as a non-fatal error to the
                        OS, the substitution may take no more than 10 times the length
                        of time of a critical check exception process. The firmware
                        makes a best effort to load the decrementer with a value that
                        represents the value in the failed processor at</para>
                        <para>the time of the machine check minus a value that
                        represents the time taken by the substitution process.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Mark the processor unsafe, do not return to the OS on
                        that processor and notify the OS to at the next event scan time
                        with a fatal return message.</para>
                        <para><emphasis role="bold">Note:</emphasis> This action 
                        may cause the OS to &#8220;hang&#8221;
                        due to locks held by the failing processor etc. that may cause
                        a surveillance time out. The NVRAM firmware error log retains a
                        trail of this condition for reading and logging at the
                        subsequent OS boot. However, in those cases where a hang does
                        not happen, the OS can select some other processor to pick up
                        the thread of execution.</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> RTAS must implement the 
              <emphasis>ibm,nmi-interlock</emphasis> call using the Argument buffer
              defined in 
              <xref linkend="dbdoclet.50569332_20517" /> which causes the release of the
              machine check work and reporting area in page 7.</para>
        
              <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20517">
                <title>Argument Call Buffer
                <emphasis>ibm,nmi-interlock</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">
                        <para>In</para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis>Token</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>Token for 
                        <emphasis>ibm,nmi-interlock</emphasis></para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number of Inputs</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>0</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>
                          <emphasis>Number of 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>0: Success</para>
                        <para>-1: Hardware Error</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> The
              
              <emphasis>ibm,nmi-interlock</emphasis> RTAS call must not require
              serialization with respect to any other RTAS or hypervisor calls.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_12478" 
          xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the FWNMI option:</emphasis> The
              processor receiving the nmi signal must, after it
              has processed the buffer pointed to by its R3 register, call the 
              <emphasis>ibm,nmi-interlock</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>
    
    <section xml:id="dbdoclet.50569332_64473">
      <title>Memory Statistics</title>
      
      <para>Depending upon the platform configuration, various portions of
      installed platform memory are in one of several states. Some memory may
      be mapped out of the address space due to an error in one or more
      locations. Other memory is used by the platform firmware. What is left is
      allocated to one or more logical partitions or held in reserve. The usage
      of memory is a first order platform management parameter, and is needed
      by platform managers. However, it may also become a covert channel
      between logical partitions. Therefore, the memory usage information that
      is surfaced to an OS image by firmware is restricted to total platform
      memory installed, plus three sub-divisions which total to the total
      memory installed. These three sub-divisions are the total memory the
      platform mapped out due to hardware failure, total memory reserved for
      platform firmware and other partitions, and the memory allocated to the
      calling OS image. LPAR machines can provide a more detailed memory usage
      report via their Hardware Management Console. The total memory allocated
      to the calling OS image is obtained through the device tree (potentially
      modified by post boot dynamic reconfiguration).</para>
    </section>
    
    <section xml:id="dbdoclet.50569332_24237">
      <title>System Parameters Option</title>
      
      <para>The system parameters which are defined are shown in 
      <xref linkend="dbdoclet.50569332_59020" />.</para>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_59020">
        <title>Defined Parameters</title>
        <tgroup cols="5">
          <colspec colname="c1" colwidth="20*" />
          <colspec colname="c2" colwidth="20*" />
          <colspec colname="c3" colwidth="20*" />
          <colspec colname="c4" colwidth="20*" />
          <colspec colname="c5" colwidth="20*" />
          <thead>
            <row>
              <entry>
                <para>
                  <emphasis role="bold">Parameter token</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Parameter</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Description</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Values</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Notes</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>HMC 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>1</para>
              </entry>
              <entry>
                <para>HMC 1</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>2 thru 15</para>
              </entry>
              <entry>
                <para>HMC 2 thru 15</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>16</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>17</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <!-- TODO: Fix this reference... -->
              <entry xml:id="dbdoclet.50569332_66206">
                <para>18</para>
              </entry>
              <entry>
                <para>Processor CoD Capacity Card Info</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_47931" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>19</para>
              </entry>
              <entry>
                <para>Memory CoD Capacity Card Info</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_47931" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>20</para>
              </entry>
              <entry>
                <para>SPLPAR Characteristics</para>
              </entry>
              <entry>
                <para>Opaque ASCII NULL terminated string</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1, 2</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>21</para>
              </entry>
              <entry>
                <para>partition_auto_restart</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_96540" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>22</para>
              </entry>
              <entry>
                <para>platform_auto_power_restart</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_96540" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>23</para>
              </entry>
              <entry>
                <para>sp-remote-pon</para>
              </entry>
              <entry>
                <para>Remote Power On</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_43497" />)</para>
              </entry>
              <entry>
                <para>One byte decimal</para>
                <para>0 (for off)</para>
                <para>1 (for on)</para>
                <para>Default 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>24</para>
              </entry>
              <entry>
                <para>sp-rb4-pon</para>
              </entry>
              <entry>
                <para>Number of rings until power on</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_43497" />)</para>
              </entry>
              <entry>
                <para>One byte decimal</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>25</para>
              </entry>
              <entry>
                <para>sp-snoop-str</para>
              </entry>
              <entry>
                <para>Snoop sequence string</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_52434" />)</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>26</para>
              </entry>
              <entry>
                <para>sp-serial-snoop</para>
              </entry>
              <entry>
                <para>Serial snoop enable/disable</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_52434" />)</para>
              </entry>
              <entry>
                <para>0 (for off)</para>
                <para>1 (for on)</para>
                <para>Default 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>27</para>
              </entry>
              <entry>
                <para>sp-sen</para>
              </entry>
              <entry>
                <para>Surveillance enable/disable</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_52434" />)</para>
              </entry>
              <entry>
                <para>0 (for off)</para>
                <para>1 (for 0n)</para>
                <para>Default 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>28</para>
              </entry>
              <entry>
                <para>sp-sti</para>
              </entry>
              <entry>
                <para>Surveillance time interval in minutes</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_52434" />)</para>
              </entry>
              <entry>
                <para>1-255</para>
                <para>Default 5</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>29</para>
              </entry>
              <entry>
                <para>sp-sdel</para>
              </entry>
              <entry>
                <para>Surveillance delay in minutes</para>
                <para>(see 
                <xref linkend="dbdoclet.50569332_52434" />)</para>
              </entry>
              <entry>
                <para>1-120</para>
                <para>Default 10</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>30</para>
              </entry>
              <entry>
                <para>sp-call-home</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_64594" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>31</para>
              </entry>
              <entry>
                <para>sp-current-flash-image</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_35911" />
                </para>
              </entry>
              <entry>
                <para>0 (for perm)</para>
                <para>1 (for temp)</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>32</para>
              </entry>
              <entry>
                <para>platform-dump-max-size</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_72712" />
                </para>
              </entry>
              <entry>
                <para>64-bit integer</para>
              </entry>
              <entry>
                <para>The value consists of a 32-bit high value followed by a
                32-bit low value. The resulting 64-bit value is
                unsigned.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>33</para>
              </entry>
              <entry>
                <para>epow3-quiesce-time</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_55444" />
                </para>
              </entry>
              <entry>
                <para>0-65535 seconds</para>
                <para>Default 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>34</para>
              </entry>
              <entry>
                <para>memory-preservation-boot-time</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_55444" />
                </para>
              </entry>
              <entry>
                <para>0-65535 seconds</para>
                <para>Default 0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>35</para>
              </entry>
              <entry>
                <para>SCSI Initiator Identifier</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_14057" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>36</para>
              </entry>
              <entry>
                <para>AIX support</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>37</para>
              </entry>
              <entry>
                <para>Enhanced Processor CoD Capacity information</para>
              </entry>
              <entry morerows="1">
                <para>
                  <xref linkend="dbdoclet.50569332_31668" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>38</para>
              </entry>
              <entry>
                <para>Enhanced Memory CoD Capacity information</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>39</para>
              </entry>
              <entry>
                <para>CoD options</para>
              </entry>
              <entry>
                <para>See 
                <xref linkend="dbdoclet.50569332_70696" />.</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>40</para>
              </entry>
              <entry>
                <para>Platform Error Classification</para>
              </entry>
              <entry>
                <para>See 
                <xref linkend="dbdoclet.50569332_65017" />.</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>41</para>
              </entry>
              <entry>
                <para>Firmware Boot Options</para>
              </entry>
              <entry>
                <para>See 
                <xref linkend="dbdoclet.50569332_93780" />.</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>42</para>
              </entry>
              <entry>
                <para>platform-processor-diagnostics-run-mode</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_93122" />
                </para>
              </entry>
              <entry>
                <para>One byte decimal</para>
                <para>0=disabled</para>
                <para>1=staggered</para>
                <para>2=immediate</para>
                <para>3=periodic</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>43</para>
              </entry>
              <entry>
                <para>Processor Module Information</para>
              </entry>
              <entry>
                <para>See 
                <xref linkend="dbdoclet.50569332_64713" />.</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>44</para>
              </entry>
              <entry>
                <para>Cooperative Memory Over-commitment Definitions</para>
              </entry>
              <entry>
                <para>Opaque ASCII NULL terminated string</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>1, 3</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>45</para>
              </entry>
              <entry>
                <para>Cede Latency Settings Information</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_63170" />
                </para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>46</para>
              </entry>
              <entry>
                <para>Target Active Memory Compression Factor</para>
              </entry>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569332_81972" />
                </para>
              </entry>
              <entry>
                <para>Field length: 2 bytes</para>
                <para>Format: binary</para>
                <para>Range: 100 -- 1000</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>47</para>
              </entry>
              <entry>
                <para>Performance boost modes vector</para>
              </entry>
              <entry>
                <para>See 
                <xref linkend="dbdoclet.50569332_57301" />.</para>
              </entry>
              <entry>
                <para>From 
                <emphasis>ibm,get-system-parameter</emphasis> the field length
                is 96 bytes consisting of 3 32 byte bit vectors. To 
                <emphasis>ibm,set-system-parameter</emphasis> the field is a
                single 32 byte bit vector</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>48</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>49</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>50</para>
              </entry>
              <entry>
                <para>TLB Block Invalidate Characteristics</para>
              </entry>
              <entry>
                <para>Variable Length Series of Bytes</para>
              </entry>
              <entry>
                <para>See <xref linkend="sec_tlb_block_invalidate" /></para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>51</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>52</para>
              </entry>
              <entry>
                <para>Energy Management Tuning Parameters</para>
              </entry>
              <entry>
                <para>Series of 8 byte entries of bytes encoding the tuning parameters supported by the system</para>
              </entry>
              <entry>
                <para>See <xref linkend="sec_energy_management_tuning_parameters" /></para>
              </entry>
              <entry>
                <para>Used by <emphasis>ibm,get-system-parameter</emphasis>; not supported for 
                <emphasis>ibm,set-system-parameter</emphasis>.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>53</para>
              </entry>
              <entry>
                <para>Firmware Service Expiration Date</para>
              </entry>
              <entry>
                <para>This is the date a system's system firmware service warranty 
                period expires. </para>
              </entry>
              <entry>
                <para>8-character null-terminated ASCII string in YYYYMMDD format</para>
              </entry>
              <entry>
                <para>Used by <emphasis>ibm,get-system-parameter</emphasis>; not supported for 
                <emphasis>ibm,set-system-parameter</emphasis>.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>54</para>
              </entry>
              <entry>
                <para>Firmware Service Entitlement Activation Key</para>
              </entry>
              <entry>
                <para>This is the activation key used to set or extend a system's firmware service 
                warranty period.</para>
              </entry>
              <entry>
                <para>34-character null-terminated ASCII string key value</para>
              </entry>
              <entry>
                <para>Used by ibm,set-system-parameter; not supported for ibm,get-system-parameter</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>55</para>
              </entry>
              <entry>
                <para>LPAR Name</para>
              </entry>
              <entry>
                <para>Logical Partition name</para>
              </entry>
              <entry>
                <para>Null-terminated ASCII string</para>
              </entry>
              <entry>
                <para>Used by ibm,set-system-parameter; not supported for ibm,get-system-parameter</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&gt;55</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
        <emphasis role="bold">Notes:</emphasis>
      </para>
      
      <orderedlist>		      
        <listitem>
          <para>These system parameters are defined for the 
          <emphasis>ibm,get-system-parameter</emphasis> RTAS call only. An attempt
          to set them using the 
          <emphasis>ibm,set-system-parameter</emphasis> RTAS call results in a
          return 
          <emphasis>Status</emphasis> of -9002 (Setting not
          allowed/authorized).</para>
        </listitem>

        <listitem>
          <para>The format of the SPLPAR string is beyond the scope of this
          architecture. See also, 
          <xref linkend="LoPAR.Virtualization" />.</para>
        </listitem>

        <listitem>
          <para>See <xref linkend="dbdoclet.50569382_58396" />.</para>
          <para>Further parameters will be defined as required.</para>
        </listitem>
      </orderedlist>		      
      

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para>All platforms must support the System
              Parameters option.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis>(Requirement Number Reserved For
              Compatibility)</emphasis></para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> If the length of
              the data for a parameter in 
              <xref linkend="dbdoclet.50569332_59020" /> is less than what is specified
              in the requirements for a parameter or if the data value in an 
              <emphasis>ibm,set-system-parameter</emphasis> RTAS call is other than what
              is allowed by the requirements for the parameter, the platform must
              return a -9999 indicating a parameter error.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis>
              The default values
              defined for parameters sp-sen, sp-sti and sp-sdel in the 
              <xref linkend="dbdoclet.50569332_59020" /> must apply to the platform
              prior to any 
              <emphasis>ibm,set-system-parameter</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
              <emphasis>ibm,get-system-parameter</emphasis> RTAS call must implement the
              argument call buffer defined by 
              <xref linkend="dbdoclet.50569332_32515" />. If the 
              <emphasis>ibm,set-system-parameter</emphasis> RTAS call is implemented, it
              must use the argument call buffer defined by 
              <xref linkend="dbdoclet.50569332_81222" />.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> If the platform
              implements the 
              <emphasis>ibm,set-system-parameter</emphasis> RTAS call it must also
              implement the 
              <emphasis>ibm,get-system-parameter</emphasis> RTAS call.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> A system parameter,
              which is not supported by the system, must return a 
              <emphasis>Status</emphasis> of -3 (System parameter not supported) from
              the RTAS call.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> A system parameter
              for which access is not authorized, must return a 
              <emphasis>Status</emphasis> of -9002 (Not authorized) from the RTAS
              call.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> When a platform
              implements a system parameter, it must meet the definition in 
              <xref linkend="dbdoclet.50569332_59020" /> including applicable
              descriptions and notes.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> An 
              <emphasis>ibm,get-system-parameter</emphasis> RTAS call with a buffer
              length of zero (0) must return a 
              <emphasis>Status</emphasis> of
              0 (success) if the parameter is supported and
              authorized, a 
              <emphasis>Status</emphasis> of -3 if not supported, or a 
              <emphasis>Status of</emphasis>-9002 if not authorized.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> An 
              <emphasis>ibm,set-system-parameter</emphasis> RTAS call with a parameter
              length of zero (0) must return a 
              <emphasis>Status</emphasis> of
              0 (success) if the parameter is supported and
              authorized, a 
              <emphasis>Status</emphasis> of -3 if not supported, or a 
              <emphasis>Status</emphasis> of -9002 if not authorized.</para>
              <para>
              <emphasis role="bold">Programming Note:</emphasis> A partition may lose or gain
              authority for an 
              <emphasis>ibm,get-system-parameter</emphasis> or 
              <emphasis>ibm,set-system-parameter</emphasis> call dynamically. For
              instance, three consecutive calls with the same parameters could return 
              <emphasis>Status</emphasis> of success, not authorized, and
              success.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
              platform must
              enforce the length of system parameter strings as follows: input strings
              to ibm,set-system-parameters not to exceed 1024 bytes in length else the
              platform returns a Status of -9999 (parameter error) from the RTAS call;
              output strings from ibm,get-system-parameters not to exceed 4000
              bytes.</para>
            </listitem>
       	</varlistentry>
       	
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_24237" 
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the System Parameter option with the SPLPAR
              option:</emphasis> The Platform must implement parameter token 20 as
              defined in 
              <xref linkend="dbdoclet.50569332_59020" /> for 
              <emphasis>ibm,get-system-parameter</emphasis>.</para>
              <para>
              <emphasis role="bold">Implementation Note:</emphasis> Of course the OS is allowed to
              provide and specify a buffer that is larger than the maximum system
              parameter length.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="dbdoclet.50569332_62190">
        <title><emphasis>ibm,get-system-parameter</emphasis></title>
  
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_32515">
          <title>Argument Call Buffer
          <emphasis>ibm,get-system-parameter</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">
                  <para>In</para>
                </entry>
                <entry>
                  <para>
                    <emphasis>Token</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Token for 
                  <emphasis>ibm,get-system-parameter</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>Parameter</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Token of system parameter to retrieve</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>
                    <emphasis>buffer</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Real address of data buffer</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>
                    <emphasis>length</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>length of data buffer</para>
                </entry>
              </row>
              <row>
                <entry morerows="1">
                  <para>Out</para>
                </entry>
                <entry morerows="1">
                  <para>
                    <emphasis>Status</emphasis>
                  </para>
                </entry>
                <entry morerows="0">
                  <para>0: Success</para>
                  <para>-1: Hardware Error</para>
                  <para>-2: Busy, Try again later</para>
                  <para>-3: System parameter not supported</para>
                  <para>-9002: Not authorized</para>
                  <para>-9999: Parameter Error</para>
                  <para>990x: Extended delay where x is a number 0-5 (see text
                  below)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para />
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The 
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call fetches the data
        for the selected parameter and places it at the address specified in the
        buffer operand. The first two (2) bytes of the data in the buffer are the
        length of the returned data, not counting these first two (2) bytes. The
        length of string data includes the length of the NULL but excludes the
        length field. If the buffer length is less than the returned data length,
        the data is truncated at the end of the buffer. The maximum length of the
        input parameter data string for 
        <emphasis>ibm,set-system-parameter</emphasis> is architecturally limited
        to 1024 bytes of data and 2 bytes of length, totaling 1026 bytes. The
        maximum length of the output parameter data string for
        ibm,get-system-parameter is architecturally limited to 4000 bytes of data
        and 2 bytes of length, totaling 4002 bytes. The only currently valid
        parameters are as specified in 
        <xref linkend="dbdoclet.50569332_59020" />.</para>
        <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-system-parameter</emphasis> with the same parameter
        index. However, software may issue the 
        <emphasis>ibm,get-system-parameter</emphasis> call again either earlier or
        later than this.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_31665">
        <title><emphasis>ibm,set-system-parameter</emphasis></title>
  
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_81222">
          <title>Argument Call Buffer
          <emphasis>ibm,set-system-parameter</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">
                  <para>In</para>
                </entry>
                <entry>
                  <para>
                    <emphasis>Token</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Token for 
                  <emphasis>ibm,set-system-parameter</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>Parameter</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Token number of the target system parameter</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>
                    <emphasis>buffer</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>Real address of data buffer</para>
                </entry>
              </row>
              <row>
                <entry morerows="1">
                  <para>Out</para>
                </entry>
                <entry morerows="1">
                  <para>
                    <emphasis>Status</emphasis>
                  </para>
                </entry>
                <entry morerows="0">
                  <para>0: Success</para>
                  <para>-1: Hardware Error</para>
                  <para>-2: Busy, Try again later</para>
                  <para>-3: System parameter not supported</para>
                  <para>-9002: Setting not allowed/authorized</para>
                  <para>-9999: Parameter Error</para>
                  <para>990x:Extended delay where x is a number 0-5 (see text
                  below)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para />
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The 
        <emphasis>ibm,set-system-parameter</emphasis> RTAS call fetches the data
        from the address specified in the buffer operand and sets it into the
        system parameter specified by the 
        <emphasis>Parameter</emphasis> operand. The first two (2) bytes of the
        data in the buffer are the length of the data, not counting these first
        two (2) bytes. The length of string data includes the length of the NULL
        but excludes the length field. The only currently valid parameters are as
        specified in 
        <xref linkend="dbdoclet.50569332_59020" />.</para>
        <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,set-system-parameter</emphasis> with the same parameter
        index. However, software may issue the 
        <emphasis>ibm,set-system-parameter</emphasis> call again either earlier or
        later than this.</para>
      </section>
      
      <section xml:id="sec_hmc_param">
        <title>HMC Parameter</title>
        <para>The full HMC parameter data string is returned when the 
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call is issued.</para>
        <para>HMC parameter contents are:</para>
        <para>length - two byte binary length of data string associated with the
        HMC.</para>
        <para>System Parameter Data - string of semicolon delimited ASCII
        data.</para>
        <para>The
        <emphasis>ibm,set-system-parameter</emphasis> is not required to support
        the HMC parameter since the HMC parameter data is set only by the HMC
        through an out-of-band path. The 
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call is provided for
        reading the parameter data. The RTAS call is available in both LPAR mode
        and non-LPAR mode.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> If the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS call is provided, the
                use of the HMC parameters, 0-15, must always return not authorized 
                <emphasis>Status</emphasis>, -9002.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> The 
                format of each HMC system
                parameter supported by this system must consist of a two byte binary
                length field describing the full length of the parameter data, followed
                by a series of variables where each variable is of the form
                &#8220;keyword&#8221; followed by &#8220;=&#8221; followed by
                &#8220;value&#8221; and terminated by &#8220;;&#8221;. The order of the
                variables is undefined and the total number of variables is undefined.
                The platform must provide the &#8220;HscIPAddr&#8221; keyword
                <footnote xml:id="pgfId-1032748">
                  <para>The acronym &#8220;HSC&#8221; was replaced by &#8220;HMC&#8221;
                  but this keyword was retained with &#8220;Hsc&#8221; so as to not
                  invalidate code already created using the keyword.</para>
                </footnote>, and the &#8220;RMCKey&#8221; keyword. The data after the
                equal sign (=) may or may not have content. The value of the
                &#8220;HscIPAddr&#8221; keyword is the IP address of that HMC. The value
                of the &#8220;RMCKey&#8221; keyword is either null or is the RMC key for
                that system or partition. The value of a keyword is null if there is
                nothing between the &#8220;=&#8221; and the &#8220;;&#8221;. The update
                state of keyword values of an HMC system parameter are uncertain when the
                HMC stops talking to the managed system.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> All 
                HMC system parameter data
                must be printable ASCII characters, excluding the two byte binary length
                field.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> The 
                lowest valued HMC system
                parameter which returns a -3 
                <emphasis>Status</emphasis> must have no higher valued HMC system
                parameter which is supported. That is, a scan of HMC system parameters
                from 0 until the first -3 
                <emphasis>Status</emphasis> must indicate all supported HMC system
                parameters.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> If 
                there is no HMC control of
                this platform, the platform must return a null response, zero length
                data, to requests for all supported HMC system parameters.</para>
                <para>
                <emphasis role="bold">Implementation Note:</emphasis> Since the system is not
                necessarily to be HMC controlled, it is shipped with the HMC parameter
                set to the zero (0) length. If the system is HMC controlled, the HMC
                passes the parameter values to the system at boot time so that the 
                <emphasis>ibm,get-system-parameters</emphasis> RTAS call indicates HMC
                control. If there is deconfigured the HMC can write the zero (0) length
                data to the system. If that is not done, the system can write the
                parameter to zero length on a hard reset and the HMC, if present, then
                initializes the data.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_hmc_param" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the HMC Parameter:</emphasis> The 
                platform must truncate the
                HMC system parameter data at the buffer length if the buffer length is
                less than the data length plus 2.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_41873">
        <title>Capacity on Demand (CoD) Option</title>
        
        <para>Platforms may optionally provide mechanisms for securely licensing
        a subset of the platform&#8217;s physically installed resources for use.
        The CoD option includes system parameters relating to the CoD Capacity
        &#8220;smart card&#8221; which is used to securely store and validate the
        license information. Dynamically adding memory and cpu resources to
        running partitions requires the CoD option combined with the Logical
        Resource Dynamic Reconfiguration option.</para>
        <para>Additionally platforms may provide a provisional CoD activation
        mode known as &#8220;Trial CoD&#8221;. This mode provides immediate
        availability of resources while the permanent license is on order. The
        CoD resources are made available for a platform dependent period of power
        on hours.</para>
        <para>If the platform implements the CoD sparing option and the platform
        predicts the failure of a CoD resource, given that there is spare
        capacity of that resource, the platform makes available a spare resource
        so that the OS can migrate work off the failing resource and return the
        failing resource to the OS. If the OS takes advantage of this sparing, by
        actually using the available resource the OS is using resources in excess
        of the permanently licensed entitlement until the failing CoD resource is
        returned to the platform.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_41873" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CoD option:</emphasis> The 
                platform must support the System Parameter option 
                (<emphasis>ibm,get-system-parameter</emphasis>)
                 along with Parameter tokens 18 
                <xref linkend="dbdoclet.50569332_66206" /> and 19 as described in 
                <xref linkend="dbdoclet.50569332_59020" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <section xml:id="dbdoclet.50569332_47931">
          <title>CoD Capacity Card Info</title>
          
          <para>
          <emphasis role="bold">Software Note:</emphasis> System parameters 18 and 19 present
          only permanently activated capacity. These parameters will be removed at
          some point in the future. OSs should begin using the enhanced CoD
          Capacity parameters.</para>
          <para>These two read only system parameters (one for memory and another
          for processors) are ASCII hexadecimal strings representing the current
          licensed entitlement of CoD resources of their respective types. These
          strings contains 9 packed fields as presented in 
          <xref linkend="dbdoclet.50569332_50150" />.</para>
    
          <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_50150">
            <title>CoD Capacity Card Info String Packed Fields</title>
            <tgroup cols="2">
              <colspec colname="c1" colwidth="50*" />
              <colspec colname="c2" colwidth="50*" />
              <thead>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Field Number</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Definition</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>System type (4 ASCII characters) (4 bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>2</para>
                  </entry>
                  <entry>
                    <para>System serial number (8 ASCII characters: pp-sssss) (8
                    bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>3</para>
                  </entry>
                  <entry>
                    <para>CoD capacity card Custom Card Identification Number
                    (CCIN) (4 ASCII characters) (4 bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>4</para>
                  </entry>
                  <entry>
                    <para>CoD capacity card serial number (10 ASCII characters:
                    pp-sssssss) (10 bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>5</para>
                  </entry>
                  <entry>
                    <para>CoD capacity card unique ID (16 ASCII characters) (16
                    bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>6</para>
                  </entry>
                  <entry>
                    <para>CoD resource identifier (4 ASCII characters) (4
                    bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>7</para>
                  </entry>
                  <entry>
                    <para>Quantity of Activated CoD resource (4 characters ASCII)
                    (4 bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>8</para>
                  </entry>
                  <entry>
                    <para>CoD sequence number (4 numeric ASCII characters) (4
                    bytes)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>9</para>
                  </entry>
                  <entry>
                    <para>CoD activation code entry check (1 byte hex check sum,
                    two ASCII characters - based on EBCDIC representation of items:
                    1, 2, 3, 4, 5, 6, 7, and 8) (2 bytes)</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_47931" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CoD option:</emphasis> The platform&#8217;s 
                  <emphasis>ibm-get-system-parameter</emphasis> RTAS call, specifying the
                  CoD Capacity Card Info, must, upon successful completion, return the
                  ASCII representation of the information defined in 
                  <xref linkend="dbdoclet.50569332_50150" /> for the managed CoD resource
                  type specified by the system parameter token.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_47931" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CoD option:</emphasis> The platform&#8217;s 
                  <emphasis>ibm,set-system-parameter</emphasis> RTAS call specifying the CoD
                  Capacity Card Info, must not return a 
                  <emphasis>Status</emphasis> of 0 (success); the expected return is a 
                  <emphasis>Status</emphasis> of -9002 (Setting not allowed/authorized),
                  however, under special cases a 
                  <emphasis>Status</emphasis> of -1 (Hardware error), or one of the Busy or
                  Extended Delay return 
                  <emphasis>Status</emphasis> return values is allowed.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
        </section>
        
        <section xml:id="dbdoclet.50569332_61466">
          <title>Predictive Failure Sparing with Free Resources</title>
          
          <para>A platform may optionally provide an unused resource to a partition
          that is notified of a predictive failure. This allows the
          partition&#8217;s OS to transparently substitute the spare resource for
          the failing one in some situations. To take advantage of this situation,
          the partition&#8217;s OS queries the free DR slot(s) of the resource type
          to determine if a spare resource is available, and if so uses the other
          DR RTAS calls to acquire the resource. In some cases resources are free
          because they have not been assigned to partitions.</para>
          <para>A platform may optionally provide an unused CoD resource to a
          partition as a predictive failure spare. In such cases, the result of an 
          <emphasis>get-sensor-state</emphasis> (entity-sense) for the DR slot
          returns the state of &#8220;exchange&#8221;. Between the time that the OS
          takes ownership, via 
          <emphasis>set-indicator</emphasis> (allocation-state, exchange), of the
          spare CoD resource available and the OS gives up the failing resource,
          the platform exceeds the licensed entitlement for that resource.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61466" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Predictive Failure Sparing option:</emphasis>
                  The platform, upon provisionally making available a spare CoD resource in
                  response to a predictive failure, must set the CoD Resource Provisional
                  Activation timer, to time out the use of the provisionally activated
                  excess resources.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
        </section>
        
        <section xml:id="dbdoclet.50569332_31668">
          <title>Enhanced CoD Capacity Info</title>
          
          <para>These two read only system parameters (one for processor and one
          for memory) return ASCII hexadecimal strings representing the current
          licensed CoD resources.</para>
          <para>The strings are constructed with a fixed &#8220;base&#8221; section
          followed by zero or more optional sections. The definitions below show
          all optional sections. The caller should not expect the presence or order
          of all optional sections. Each optional section starts with the following
          3 members:</para>
          
          <itemizedlist>		      
            <listitem>
              <para>Offset to next section (zero for last section)</para>
            </listitem>
            
            <listitem>
              <para>Size in bytes of the section (including these three
              members)</para>
            </listitem>
            
            <listitem>
              <para>Name of the section</para>
            </listitem>
          </itemizedlist>		      
          
          <para>The specific meaning of the members of each section is beyond the
          scope of this architecture; refer to the specific platform design
          documents.</para>
          <para>All data in these tables are composed of printable ASCII
          characters. There are no NULLs or other non-printable characters.</para>
          <para>
          <emphasis role="bold">Programming Note:</emphasis> On a platform where the base
          processor capacity is a fraction of a full processor, the data in the
          BaseProc section below is rounded up to the next larger whole
          number.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_31668" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CoD option:</emphasis> The platform's 
                  <emphasis>ibm,get-system-parameter</emphasis> RTAS call, specifying the
                  Enhanced CoD Processor Capacity Info, must, upon successful completion,
                  return the ASCII representation of the information defined in 
                  <xref linkend="dbdoclet.50569332_90985" /> for managed CoD processor
                  resources.</para>
            
                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_90985">
                    <title>Enhanced CoD Processor Capacity Info, Version
                    1</title>
                    <tgroup cols="5">
                      <colspec colname="c1" colwidth="20*" />
                      <colspec colname="c2" colwidth="20*" />
                      <colspec colname="c3" colwidth="20*" />
                      <colspec colname="c4" colwidth="20*" />
                      <colspec colname="c5" colwidth="20*" />
                      <thead>
                        <row>
                          <entry>
                            <para>
                              <emphasis role="bold">Offset</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Size in Bytes</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Section</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Description</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Format</emphasis>
                            </para>
                          </entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Meta</para>
                          </entry>
                          <entry>
                            <para>Table version indicator</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters &#8220;V1 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Meta</para>
                          </entry>
                          <entry>
                            <para>Decimal number of optional sections</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>12</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;78 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;BASE &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>24</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>system type</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>28</para>
                          </entry>
                          <entry>
                            <para>10</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>System serial number</para>
                          </entry>
                          <entry>
                            <para>10 ASCII characters: &#8220;pp-ssssss &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>38</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card CCIN</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>42</para>
                          </entry>
                          <entry>
                            <para>10</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card serial number</para>
                          </entry>
                          <entry>
                            <para>10 ASCII characters &#8220;hh-hssssss&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card unique ID</para>
                          </entry>
                          <entry>
                            <para>16 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>68</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD resource identifier</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>72</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Quantity of permanently activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>76</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 numeric ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>80</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD activation code entry check</para>
                          </entry>
                          <entry>
                            <para>1 byte hex check sum, 2 ASCII characters -- based on
                            EBCDIC representation of previous 8 entries.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>82</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Total CoD resources installed in system</para>
                          </entry>
                          <entry>
                            <para>4 numeric ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>On/Off Processor Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;66 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;ONOFFPRC&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD active</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resources requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>36</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD days requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>40</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resource days expired</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>44</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resource days remaining</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD counter</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off standby resources available</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>56</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>57</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off history of requested resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>61</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffPrc</para>
                          </entry>
                          <entry>
                            <para>On/Off history of unreturned resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>Debit Processor Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;82 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;DEBITPRC&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD active</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit CoD resources requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>36</para>
                          </entry>
                          <entry>
                            <para>12</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit Reserved</para>
                          </entry>
                          <entry>
                            <para>12 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit counter</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit standby resources available</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>56</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>57</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit history of expired resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>61</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Debit history of unreturned resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>66</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Extended total history of requested On/Off Processor
                            days</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>74</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitPrc</para>
                          </entry>
                          <entry>
                            <para>Extended total history of unreturned On/Off Processor
                            days</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>Trial Processor Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;66 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;TRIALPRC&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial reserved</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial reserved bytes</para>
                          </entry>
                          <entry>
                            <para>8 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>40</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial days expired</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>44</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial days remaining</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>14</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial reserved bytes</para>
                          </entry>
                          <entry>
                            <para>14 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialPrc</para>
                          </entry>
                          <entry>
                            <para>Trial unreturned resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>Base Processor Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>BaseProc</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>BaseProc</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;20 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>BaseProc</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;BASEPROC&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>BaseProc</para>
                          </entry>
                          <entry>
                            <para>Number of Non-CoD &#8220;Base&#8221; processors on this
                            system. NOTE: If this section is not present, there are no
                            &#8220;base&#8221; processors and all processors are CoD
                            activated.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_31668" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CoD option:</emphasis> The platform's 
                  <emphasis>ibm,get-system-parameter</emphasis> RTAS call, specifying the
                  Enhanced CoD Memory Capacity Info, must, upon successful completion,
                  return the ASCII representation of the information defined in 
                  <xref linkend="dbdoclet.50569332_26496" />for the managed CoD memory
                  resources.</para>
            
                  <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26496">
                    <title>Enhanced CoD Memory Capacity Info, Version 1</title>
                    <tgroup cols="5">
                      <colspec colname="c1" colwidth="20*" />
                      <colspec colname="c2" colwidth="20*" />
                      <colspec colname="c3" colwidth="20*" />
                      <colspec colname="c4" colwidth="20*" />
                      <colspec colname="c5" colwidth="20*" />
                      <thead>
                        <row>
                          <entry>
                            <para>
                              <emphasis role="bold">Offset</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Size in Bytes</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Section</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Description</emphasis>
                            </para>
                          </entry>
                          <entry>
                            <para>
                              <emphasis role="bold">Format</emphasis>
                            </para>
                          </entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Meta</para>
                          </entry>
                          <entry>
                            <para>Table version indicator</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters &#8220;V1 &#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Meta</para>
                          </entry>
                          <entry>
                            <para>Decimal number of optional sections</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>12</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;78 &#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;BASE &#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>24</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>system type</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>28</para>
                          </entry>
                          <entry>
                            <para>10</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>System serial number</para>
                          </entry>
                          <entry>
                            <para>10 ASCII characters: &#8220;pp-ssssss &#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>38</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card CCIN</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>42</para>
                          </entry>
                          <entry>
                            <para>10</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card serial number</para>
                          </entry>
                          <entry>
                            <para>10 ASCII characters &#8220;hh-hssssss&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD capacity card unique ID</para>
                          </entry>
                          <entry>
                            <para>16 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>68</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD resource identifier</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>72</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Quantity of permanently activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>76</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 numeric ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>80</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>CoD activation code entry check</para>
                          </entry>
                          <entry>
                            <para>1 byte hex check sum, 2 ASCII characters -- based on
                            EBCDIC representation of previous 8 entries.</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>82</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>Base</para>
                          </entry>
                          <entry>
                            <para>Total CoD resources installed in system</para>
                          </entry>
                          <entry>
                            <para>4 numeric ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>On/Off Memory Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;67 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;ONOFFMEM&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD active</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resources requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>36</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD days requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>40</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resource days expired</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>44</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD resource days remaining</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off CoD counter</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off standby resources available</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>56</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>57</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off history of requested resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>61</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off history of unreturned resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>66</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>OnOffMem</para>
                          </entry>
                          <entry>
                            <para>On/Off Memory Multiplier</para>
                          </entry>
                          <entry>
                            <para>1 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>Debit Memory Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;83 &#8220;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;DEBITMEM&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD active</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit CoD resources requested</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>36</para>
                          </entry>
                          <entry>
                            <para>12</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit Reserved</para>
                          </entry>
                          <entry>
                            <para>12 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit counter</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>52</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit standby resources available</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>56</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>57</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit history of expired resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>61</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit history of unreturned resource days</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>66</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Extended total history of requested On/Off Memory GB
                            days</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>74</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Extended total history of unreturned On/Off Memory GB
                            days</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>82</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>DebitMem</para>
                          </entry>
                          <entry>
                            <para>Debit reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry nameend="c5" namest="c1">
                            <para>Trial Memory Resources</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Decimal offset in bytes from the start of this section to
                            the start of the next section (that is, the offset from the
                            first byte of this member to the first byte of the next
                            section). Zero if the last section.</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Section Length -- The length of this section in bytes
                            (including offset member above)</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters &#8220;67 &#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Section Name</para>
                          </entry>
                          <entry>
                            <para>8 ASCII characters &#8220;TRIALMEM&#8221;</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>16</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial CoD enabled</para>
                          </entry>
                          <entry>
                            <para>1 ASCII character '0' or '1'</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>17</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial reserved</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>18</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial CoD feature</para>
                          </entry>
                          <entry>
                            <para>4 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>22</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial CoD activated resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>26</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial CoD sequence number</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>30</para>
                          </entry>
                          <entry>
                            <para>2</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial CoD checksum</para>
                          </entry>
                          <entry>
                            <para>2 ASCII characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>32</para>
                          </entry>
                          <entry>
                            <para>8</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial reserved bytes</para>
                          </entry>
                          <entry>
                            <para>8 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>40</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial days expired</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>44</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial days remaining</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>48</para>
                          </entry>
                          <entry>
                            <para>14</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial reserved bytes</para>
                          </entry>
                          <entry>
                            <para>14 ASCII blanks</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>62</para>
                          </entry>
                          <entry>
                            <para>4</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial unreturned resources</para>
                          </entry>
                          <entry>
                            <para>4 ASCII numeric characters</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>66</para>
                          </entry>
                          <entry>
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>TrialMem</para>
                          </entry>
                          <entry>
                            <para>Trial reserved byte</para>
                          </entry>
                          <entry>
                            <para>1 ASCII blank</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_31668" 
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CoD option:</emphasis> The platform's 
                  <emphasis>ibm,set-system-parameter</emphasis> RTAS call specifying the
                  Enhanced CoD Capacity Info, must not return a 
                  <emphasis>Status</emphasis> of 0 (Success); the expected return is a 
                  <emphasis>Status</emphasis> of -9002 (setting not allowed/authorized),
                  however, under special cases a 
                  <emphasis>Status</emphasis> of -1 (Hardware Error) or one of the Busy or
                  Extended Delay return 
                  <emphasis>Status</emphasis> values is allowed.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
        </section>

      </section>
    
      <section xml:id="dbdoclet.50569332_96540">
        <title><emphasis>Restart Parameters</emphasis></title>
        
        <para>This section and its subsections describe parameters that govern
        the actions that the platform firmware takes upon a restart (that is,
        reboot) after an unintended termination.</para>
      
        <section xml:id="sec_partition_auto_restart_param">
          <title>partition_auto_restart Parameter</title>
          
          <para>The partition_auto_restart parameter governs whether or not
          platform firmware attempts to restart a partition after an error which
          causes an abnormal partition termination. Neither a loss of external
          power without a UPS, nor a loss of external power and battery power with
          a UPS are examples of an error which causes abnormal partition
          termination. For terminations that involve only a specific partition (for
          example, a machine check), the partition_auto_restart parameter governs
          whether the partition restarts. For terminations that span the entire
          platform (for example, a checkstop), the platform may separately govern
          whether or not the entire platform restarts. If the platform does
          restart, however, partition_auto_restart determines whether or not an
          individual partition restarts.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_partition_auto_restart_param" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the LPAR option with the System Parameters
                  option:</emphasis> If the platform supports the partition_auto_restart
                  system parameter, the platform must establish and maintain across boot
                  (unless explicitly altered by a user) for each partition the one (1) byte
                  parameter, the initial value (depending upon platform policy) is one of
                  the following binary values:</para>
                  <para>0 - Do not automatically restart the partition</para>
                  <para>1 - Automatically restart the partition</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_partition_auto_restart_param" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SMP option (non-LPAR) with the System Parameters
                  option:</emphasis> If the platform supports the partition_auto_restart
                  system parameter, the platform must establish and maintain across boot
                  (unless explicitly altered by a user) one and only one (1) byte
                  parameter, the initial value (depending upon platform policy) is one of
                  the following binary values:</para>
                  <para>0 - Do not automatically restart the OS</para>
                  <para>1 - Automatically restart the OS</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
        </section>
        
        <section xml:id="dbdoclet.50569332_99524">
          <title>platform_auto_power_restart Parameter</title>
          
          <para>The platform_auto_power_restart parameter governs whether or not
          platform firmware attempts to restart after power is restored following a
          power outage.</para>
    
          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99524" 
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the System Parameters option:</emphasis> If 
                  the platform
                  supports the platform_auto_power_restart system parameter, the platform
                  must maintain across boot (unless explicitly altered by a user) one and
                  only one platform wide value of the one (1) byte parameter having one of
                  the following binary values:</para>
                  <para>0 - Do not automatically restart</para>
                  <para>1 - Automatically restart partitions that were active when external
                  power was lost.</para>
                </listitem>
           	</varlistentry>
           	
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99524" 
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the LPAR option with the System Parameters
                  option:</emphasis> If the platform supports the
                  platform_auto_power_restart system parameter, the platform must provide
                  the authority to set and read the platform_auto_power_restart system
                  parameter to, at most, one partition at a time.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
    
        </section>
 
      </section>
      
      <section xml:id="dbdoclet.50569332_43497">
        <title>Remote Serial Port System Management Parameters</title>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option with the System Parameters
                option:</emphasis> If the platform supports any of the following system
                parameters: sp-remote-pon, sp-rb4-pon, sp-snoop-str, and sp-serial-snoop;
                the platform must grant authority to set and read the single platform
                wide values of the respective system parameters to only the partition
                owning the resource required to implement the function, such as a serial
                port, where the valid data for the parameters are specified in 
                <xref linkend="dbdoclet.50569332_59020" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
                platform must
                support the sp-rb4-pon system parameter if and only if the sp-remote-pon
                system parameter is supported and implemented by using &#8220;Ring
                Indicate&#8221; of a serial port.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option with the System Parameters
                option:</emphasis> Platforms that supports the sp-snoop-str system
                parameter must maintain one and only one platform wide NULL terminated
                ASCII string value of the parameter; granting authority to set and read
                the sp-snoop-str system parameter to, at most, one partition at a
                time.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> To prevent return
                data truncation of the returned sp-snoop-str system parameter from the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call the caller must
                supply a buffer length sufficient to contain the two string length bytes
                plus the ASCII string and the terminating ASCII NULL.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
                caller of the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call must supply a
                buffer length sufficient to contain the two string length bytes plus the
                ASCII string and the terminating ASCII NULL to prevent return data
                truncation of the returned sp-snoop-str system parameter.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_43497" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
                platform must
                supports both the sp-snoop-str and sp-serial-snoop system parameters if
                it supports either.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_52434">
        <title>Surveillance Parameters</title>
        
        <para>For the definition of the sp-sen, sp-sti, and sp-del parameters,
        see 
        <xref linkend="dbdoclet.50569332_60143" />.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_52434" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis>For the LPAR option</emphasis>
                <emphasis role="bold">with the System Parameters option:</emphasis> If the platform
                supports any of the following system parameters: sp-sen, sp-sti, or
                sp-del; the platform must grant authority to set and read the single
                platform wide one (1) byte values, where the decimal representation is
                defined in 
                <xref linkend="dbdoclet.50569332_59020" />, of the respective system
                parameters to only one partition at a time.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_52434" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> If the platform
                supports any of the sp-sen, sp-sti or sp-del system parameters, it must
                support then all.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_64594">
        <title>Call Home Parameter</title>
        
        <para>This parameter is used to provide input concerning certain call
        home values used when a call home function is provided. The data for the
        parameter is an ASCII string which provides additional information</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_64594" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option with the System Parameters
                option:</emphasis> If the platform supports the sp-call-home parameter,
                platform must grant authority to set and read the single platform wide
                value of the system parameter at any time to only one partition; where
                the data for the parameter is an ASCII string in the form
                &lt;String_name1&gt;=&lt;string&gt;&lt;ASCII
                NULL&gt;&lt;String_name2&gt;=&lt;string&gt;&lt;ASCII
                NULL&gt;....&lt;String_nameN&gt;=&lt;string&gt;&lt;ASCII
                NULL&gt;&lt;ASCII NULL&gt; with string names defined as per 
                <xref linkend="dbdoclet.50569332_38612" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_64594" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> The 
                caller of the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call must supply a
                buffer length sufficient to contain the maximum possible ASCII string
                returned, including the two ASCII NULLs where 
                <xref linkend="dbdoclet.50569332_38612" /> indicates the maximum length of
                the data for each substring that comprises the sp-call-home data, to
                prevent return data truncation of the returned sp-call-home system
                parameter.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_64594" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters 
                option:</emphasis> If the platform
                supports the sp-call-home parameter, the platform must provide the
                sp-call-home parameter value defaults listed in 
                <xref linkend="dbdoclet.50569332_38612" /> prior to any 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS call.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_38612">
                  <title>sp-call-home Strings</title>
                  <tgroup cols="5">
                    <colspec colname="c1" colwidth="20*" />
                    <colspec colname="c2" colwidth="20*" />
                    <colspec colname="c3" colwidth="20*" />
                    <colspec colname="c4" colwidth="20*" />
                    <colspec colname="c5" colwidth="20*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">String_Name</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Default</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Range</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Maximum Characters in String
                            Data</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Description</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>sp-rt-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Retry string for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-ic-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Protocol interdata block delay (*IC) for serial port
                          &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-to-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Protocol time out (*DT) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-cd-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Call Delay (*CD) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-connect-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Connect (*CX) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-disconnect-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Disconnect (*DX) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-condout-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Call-out condition (*C0) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-condwait-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Call-wait (*C0) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-condin-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Call-in condition (*C1) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-waitcall-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Wait call (*WC) for serial port &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-page-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Describes how to Page a beeper for serial port
                          &lt;N&gt;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-diok-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>off</para>
                        </entry>
                        <entry>
                          <para>on,off</para>
                        </entry>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Serial Port &lt;N&gt; Call-in (Dial in authorized on the
                          port)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-dook-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>off</para>
                        </entry>
                        <entry>
                          <para>on,off</para>
                        </entry>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Serial Port &lt;N&gt; Call-out (Dial out authorized on
                          the port)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-dookc</para>
                        </entry>
                        <entry>
                          <para>off</para>
                        </entry>
                        <entry>
                          <para>on,off</para>
                        </entry>
                        <entry>
                          <para>4</para>
                        </entry>
                        <entry>
                          <para>Call-out before restart (Dial out for system crash using
                          authorized serial port)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-ls-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>9600</para>
                        </entry>
                        <entry>
                          <para>300, 600, 1200, 2000, 2400, 3600, 4800, 7200, 9600,
                          19200, 38400</para>
                        </entry>
                        <entry>
                          <para>6</para>
                        </entry>
                        <entry>
                          <para>S&lt;N&gt; line speed</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-modemf-s&lt;N&gt;</para>
                        </entry>
                        <entry>
                          <para>NULL</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                        <entry>
                          <para>120</para>
                        </entry>
                        <entry>
                          <para>Filename of the last modem file used to configure modem
                          parameters</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-phsvc</para>
                        </entry>
                        <entry>
                          <para>20 blank characters</para>
                        </entry>
                        <entry>
                          <para>20 characters max</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Service Center Telephone Number (*PS)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-phadm</para>
                        </entry>
                        <entry>
                          <para>20 blank characters</para>
                        </entry>
                        <entry>
                          <para>20 characters max</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Customer Administration Center Telephone Number
                          (*PH)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-pager</para>
                        </entry>
                        <entry>
                          <para>20 blank characters</para>
                        </entry>
                        <entry>
                          <para>20 characters max</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Digital Pager Telephone Number</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-phsys</para>
                        </entry>
                        <entry>
                          <para>20 blank characters</para>
                        </entry>
                        <entry>
                          <para>20 characters max</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Customer System Telephone number (*PY)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-vox</para>
                        </entry>
                        <entry>
                          <para>20 blank characters</para>
                        </entry>
                        <entry>
                          <para>20 characters max</para>
                        </entry>
                        <entry>
                          <para>20</para>
                        </entry>
                        <entry>
                          <para>Customer Voice telephone number (*PO)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-acct</para>
                        </entry>
                        <entry>
                          <para>12 blank characters</para>
                        </entry>
                        <entry>
                          <para>12 characters max</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Customer Account Number (*CA)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-cop</para>
                        </entry>
                        <entry>
                          <para>first</para>
                        </entry>
                        <entry>
                          <para>first, all</para>
                        </entry>
                        <entry>
                          <para>6</para>
                        </entry>
                        <entry>
                          <para>Call-out policy (first/all) - numbers to call in case of
                          failure</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-retlogid</para>
                        </entry>
                        <entry>
                          <para>12 blank characters</para>
                        </entry>
                        <entry>
                          <para>12 characters max</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Customer RETAIN Login Userid (*LI)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-retpw</para>
                        </entry>
                        <entry>
                          <para>16 blank characters</para>
                        </entry>
                        <entry>
                          <para>16 characters max</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Customer RETAIN Login password (*PW)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-rto</para>
                        </entry>
                        <entry>
                          <para>120</para>
                        </entry>
                        <entry>
                          <para>&gt;1</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Remote Timeout (in seconds) (*RT)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-rlat</para>
                        </entry>
                        <entry>
                          <para>2</para>
                        </entry>
                        <entry>
                          <para>&gt; 1</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Remote Latency (in seconds) (*RL)</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-rn</para>
                        </entry>
                        <entry>
                          <para>2</para>
                        </entry>
                        <entry>
                          <para>0 or any positive number</para>
                        </entry>
                        <entry>
                          <para>12</para>
                        </entry>
                        <entry>
                          <para>Number of retries (while busy (*RN))</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>sp-sysname</para>
                        </entry>
                        <entry>
                          <para>15 blank characters</para>
                        </entry>
                        <entry>
                          <para>15 characters max</para>
                        </entry>
                        <entry>
                          <para>15</para>
                        </entry>
                        <entry>
                          <para>System Name (system administrator aid)</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <para>
                  <emphasis role="bold">Notes:</emphasis>
                </para>
                
                <orderedlist>		      
                  <listitem>
                    <para>&lt;N&gt; is substituted with a modem number, i.e. 1 or
                    2.</para>
                  </listitem>
          
                  <listitem>
                    <para>NULL as a default indicates that the string is given a name, but
                    no value, e.g. sp-modemf-s=</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
        </variablelist>
                
      </section>
      
      <section xml:id="dbdoclet.50569332_35911">
        <title>Current Flash Image Parameter</title>
        
        <para>In systems with storage for more than one Flash image, the
        sp-current-flash-image parameter indicates which Flash image is currently
        being used by the service processor. This is typically the Flash image
        used at the last boot.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_35911" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis>For the LPAR option</emphasis>
                <emphasis role="bold">with the System Parameters option:</emphasis> Platforms that
                supports the sp-current-flash-image system parameter, must authorize all
                partitions to get the single platform wide one (1) byte value of the
                system parameter, whose decimal representation is defined in 
                <xref linkend="dbdoclet.50569332_59020" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_35911" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the System Parameters option:</emphasis> Platforms that
                supports the sp-current-flash-image system parameter must support the 
                <emphasis>ibm,manage-flash-image</emphasis> RTAS call.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_72712">
        <title>Platform Dump Max Size Parameter</title>
        
        <para>This parameter indicates the size (in bytes) needed for dumps
        returned from the 
        <emphasis>ibm,platform-dump</emphasis> RTAS function.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72712" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Platform Dump option:</emphasis> If the 
                <emphasis>ibm,platform-dump</emphasis> RTAS call is authorized for the
                partition, the platform must authorize the partition to get the
                platform-dump-max-size system parameter; where the value returned must
                indicate the sum (in bytes) of the maximum size of each unique platform
                dump type that the 
                <emphasis>ibm,platform-dump</emphasis> RTAS call could return.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Programming Note:</emphasis> The intent of
        platform-dump-max-size is for the platform to specify, in advance, the
        sum of the maximum sizes of all the unique dump types that it can
        generate. This is to allow the OS to reserve space for one log of each
        type. In the case of any change in the value of this parameter, the
        platform may generate a Platform Event Log entry announcing the change in
        the maximum size, and specifying the new size in the IO Events Section.
        This entry, when generated, is then returned by the 
        <emphasis>event-scan</emphasis> RTAS call.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_55444">
        <title>Storage Preservation Option System Parameters</title>
        
        <para>The epow3-quiesce-time system parameter contains the time granted
        to the current instance of a client program to perform quiesce activities
        in preparation for a memory preservation boot. This quiesce time is the
        time used by the client program to do such things as quiesce and power
        off I/O not needed for memory preservation boot processing, in order to
        conserve batteries. A client program utilizing the Storage Preservation
        option, upon completion of quiesce activities, requests a reboot. The
        platform, upon seeing an EPOW class 3 condition, and if both the
        memory-preservation-boot-time and epow3-quiesce-time system parameters
        are non-zero, starts a timer with an initial value equal to the
        epow3-quiesce-time. If the timer expires before the client program
        performs a reboot, the platform forces a reboot of the client
        program.</para>
        <para>The memory-preservation-boot-time system parameter contains the
        time granted to the rebooted instance of the partition to perform the
        saving of preserved memory. The client program, upon completion of the
        saving of preserved memory, requests a shutdown. The platform, upon
        initiation of a memory preservation boot starts a timer with an initial
        value equal to the memory-preservation-boot-time, providing the value of
        the memory-preservation-boot-time parameter is non-zero. If the timer
        expires before the client program performs a shutdown, the platform
        forces a shutdown of the client program.</para>
        <para>Thus, the platform uses the memory-preservation-boot-time system
        parameter as a policy attribute. If the client program has set the value
        of this parameter to a non-zero value, then the memory preservation boot
        timers are enabled. If the memory-preservation-boot-time parameter is
        zero (independent of the epow3-quiesce-time setting), the platform does
        not initiate the memory preservation boot timers.</para>
        <para>To use the memory preservation boot timers, the client program
        registers its LMBs for preservation and sets the
        memory-preservation-boot-time via the 
        <emphasis>ibm,set-system-parameter</emphasis> RTAS call. If an EPOW class
        3 is sent to a client program and the client program has set its
        memory-preservation-boot-time parameter, then the platform starts the
        timer for epow3-quiesce-time. The client program on reboot uses the 
        <emphasis>get-sensor</emphasis> RTAS call (to detect EPOW condition) and
        the 
        <emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis> property in the
        device tree to drive memory preservation processing as necessary. The
        values of memory-preservation-boot-time and epow3-quiesce-time prior to
        being set for a client program are 0. These system parameters are
        persisted, as are all system parameters.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_55444" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
                must implement the memory-preservation-boot-time and epow3-quiesce-time
                system parameters and must set their initial values to 0.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_55444" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Storage Preservation option:</emphasis> If the
                memory-preservation-boot-time system parameter is non-zero for a client
                program and if the platform delivers an EPOW class 3 indication to the
                client program, the platform must do all of the following:</para>
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>Upon delivering the EPOW class 3 to the client program, if the
                    epow3-quiesce-time system parameter is non-zero, then set a timer based
                    on the client program&#8217;s epow3-quiesce-time system parameter and
                    force a reboot of the client program on timer expiration, if the client
                    program does not request a reboot itself before the timer expires.</para>
                  </listitem>
          
                  <listitem>
                    <para>Upon initiation of the memory preservation boot, set a timer
                    based on the client program&#8217;s memory-preservation-boot-time system
                    parameter and on timer expiration, force a shutdown of the client program
                    if the client program does not request a shutdown itself before the timer
                    expires.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
        </variablelist>
        
      </section>
      
      <section xml:id="dbdoclet.50569332_14057">
        <title>SCSI Initiator Identifier System Parameters</title>
        
        <para>Certain physical SCSI IOAs maintain their previous settings for
        SCSI initiator identifier, while others require that the platform set
        this value during I/O adapter initialization. Since the initialization of
        I/O adapters in the boot path is done by firmware, a method is required
        for the OS to inform the platform firmware of such settings. Given that
        an OS owns a slot, and that slot contains a supported SCSI I/O adapter,
        the OS may use the 
        <emphasis>ibm,set-system-parameter</emphasis> RTAS call specifying SCSI
        Initiator Identifier system parameters to instruct the firmware how to
        initialize the I/O adapter to ensure that it does not conflict with other
        SCSI initiators on the same bus. The 
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call is used to verify
        the SCSI Initiator Identifier system parameters value for any OS owned
        slot.</para>
        <para>When 
        <emphasis>ibm,set-system-parameter</emphasis> is called specifying SCSI
        Initiator Identifier system parameters, the buffer contains the standard
        two byte length field plus two NULL terminated strings. The first string
        contains the location code of an I/O Adapter's SCSI bus connector, and
        the second string contains one of the decimal values 0-15 representing
        the value of the SCSI Initiator Identifier that the platform's firmware
        is to use to initialize the SCSI controller for that bus.</para>
        <para>When 
        <emphasis>ibm,get-system-parameter</emphasis> is called specifying SCSI
        Initiator Identifier system parameters, the buffer contains the standard
        two byte length field plus a NULL terminated string that contains the
        location code of an I/O Adapter's SCSI bus connector. Upon successful
        return, the buffer contains the standard two byte length field plus two
        NULL terminated strings. The first string contains the location code of
        the I/O Adapter's SCSI bus connector, and the second string contains one
        of the decimal values 0-15 representing the value of the SCSI Initiator
        Identifier that the platform's firmware is to use to initialize the SCSI
        controller for that bus.</para>
        <para>
        <emphasis role="bold">Implementation Note:</emphasis> For IOAs that have multiple
        connectors per bus, the location code specifies the connector for the
        external bus.</para>
        <para>Interaction between SCSI Initiator Identifier system parameters and
        DR operations produce unique situations. The platform maintains only the
        latest SCSI Initiator Identifier set for any given location code. On DR
        operations, the value is normally retained until the IOA owner explicitly
        changes it. If a DR operation replaces the original IOA with a different
        type of IOA, such that the previously set SCSI Initiator Identifier
        system parameters no longer make sense (IOA is not a supported SCSI
        adapter or the connector location codes do not match), the platform
        firmware clears the SCSI Initiator Identifier system parameters for the
        location code and performs the platform default IOA
        initialization.</para>
  
        <variablelist>
         	<varlistentry xml:id="dbdoclet.50569332_38676">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,set-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, RTAS must return 
                <emphasis>Status</emphasis> of -3 (Parameter error) on any of the
                following conditions:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The binary value of the first two bytes in the buffer, plus 2,
                    is greater than the buffer length parameter.</para>
                  </listitem>
          
                  <listitem>
                    <para>The buffer length parameter is greater than 1026.</para>
                  </listitem>
          
                  <listitem>
                    <para>The N bytes of buffer contents (N being the binary value of the
                    first two buffer bytes) does not contain two NULL terminated
                    strings.</para>
                  </listitem>
          
                  <listitem>
                    <para>The contents of the first NULL terminated buffer string does not
                    match the format of a valid platform location code.</para>
                  </listitem>
          
                  <listitem>
                    <para>The contents of the second NULL terminated buffer string does
                    not contain a decimal value in the range of 0 to 15.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_51807">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,set-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_38676" />, the first NULL terminated
                buffer string must contain a valid formatted platform location code for a
                currently installed slot owned by the calling OS, or the platform must
                return &#8220;Not authorized&#8221; 
                <emphasis>Status</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_21338">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,set-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_51807" />, the first NULL terminated
                buffer string must contain a valid formatted platform location code for a
                SCSI bus connector of a supported SCSI I/O adapter currently installed in
                a slot owned by the calling OS, or the platform must return
                &#8220;Parameter Error&#8221; 
                <emphasis>Status</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis> When 
                <emphasis>ibm,set-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_21338" />, the firmware must record the
                value supplied in the second NULL terminated buffer string for use in
                initializing the SCSI initiator identifier of the SCSI I/O adapter
                contained in the slot specified by the first NULL terminated buffer
                string and return a 
                <emphasis>Status</emphasis> of 0 (success) (except in the case of hardware
                errors or busy conditions).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_38737">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,get-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, RTAS must return a 
                <emphasis>Status</emphasis> of -3 (Parameter error) on any of the
                following conditions:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The binary value of the first two bytes in the buffer, plus 2,
                    is greater than the buffer length parameter.</para>
                  </listitem>
          
                  <listitem>
                    <para>The buffer length parameter is greater than 1026.</para>
                  </listitem>
          
                  <listitem>
                    <para>The N bytes of buffer contents (N being the binary value of the
                    first two buffer bytes) does not contain one NULL terminated
                    string.</para>
                  </listitem>
          
                  <listitem>
                    <para>The contents of the NULL terminated buffer string does not match
                    the format of a valid platform location code.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_95088">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,get-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_38737" />, the NULL terminated buffer
                string must contain a valid formatted platform location code for a
                currently installed slot owned by the calling OS, or the platform must
                return &#8220;Not authorized&#8221; 
                <emphasis>Status</emphasis>.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry xml:id="dbdoclet.50569332_24869">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis>
                When <emphasis>ibm,get-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_95088" />, the NULL terminated buffer
                string must contain a valid formatted platform location code for a SCSI
                bus connector of a supported SCSI I/O adapter currently installed in a
                slot owned by the calling OS, or the platform must return a 
                <emphasis>Status</emphasis> of -3 (parameter error).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis> When 
                <emphasis>ibm,get-system-parameter</emphasis> is called specifying SCSI
                Initiator Identifier system parameters, and the request successfully
                passes the Requirements of 
                <xref linkend="dbdoclet.50569332_24869" />, the firmware must:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>Increase the value contained in the first two bytes of the
                    buffer to cover both the length of the location code NULL terminated
                    string and a NULL terminated string representing the decimal value that
                    the platform uses to initialize the SCSI initiator identifier of the SCSI
                    I/O adapter contained in the slot specified by the first NULL terminated
                    buffer string.</para>
                  </listitem>
          
                  <listitem>
                    <para>If there is room in the buffer, append the NULL terminated
                    string representing the decimal value that the platform uses to
                    initialize the SCSI initiator identifier of the SCSI I/O adapter
                    contained in the slot specified by the first NULL terminated buffer
                    string.</para>
                  </listitem>
          
                  <listitem>
                    <para>Return a <emphasis>Status</emphasis> of 0 (success) (except in the 
                    case of hardware errors or busy conditions).</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14057" 
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SCSI Initiator Identifier System Parameters
                option:</emphasis> When the platform firmware initializes an IOA and a
                SCSI Initiator Identifier system parameter is set for that IOA's slot
                location code, and the SCSI Initiator Identifier system parameter is
                incompatible with the currently installed IOA (IOA is not a supported
                SCSI adapter or the connector location codes do not match a SCSI bus
                connector for that IOA), the platform must clear the incompatible SCSI
                Initiator Identifier system parameter and proceed to initialize the IOA
                using platform default behaviors.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
      </section>
      
      <section xml:id="dbdoclet.50569332_70696">
        <title>CoD Options</title>
        
        <para>The CoD Options system parameter allows specification of various
        CoD options.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_70696" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis>ibm,get-system-parameter</emphasis> is called 
                specifying the CoD Options system parameter, the first 
                two bytes of the value returned must
                contain the full length of the parameter data, including the length of
                the NULL. The two byte binary length field is followed by a variable of
                the form &#8220;keyword&#8221; followed by &#8220;=&#8221; followed by
                &#8220;value&#8221; and terminated by a semicolon (&#8220;;&#8221;),
                where the contents of &#8220;value&#8221; must be an ASCII printable
                character string.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_70696" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>The corresponding keyword and values
                for the CoD Options parameter are defined in 
                <xref linkend="dbdoclet.50569332_55240" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55240">
                  <title>CoD Options System Parameter Keyword and
                  Values</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">Keyword</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Permitted Values</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Definition</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>LPoptions</para>
                        </entry>
                        <entry>
                          <para>yes, no</para>
                        </entry>
                        <entry>
                          <para>no: The platform does not support the Low Priced adapters
                          and devices.</para>
                          <para>yes: The platform supports the Low Priced adapters and
                          devices.</para>
                          <para>Absence of the keyword is the same as the keyword with
                          the value of &#8220;yes&#8221;.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_65017">
        <title>Platform Error Classification</title>
        
        <para>The Platform Error Classification system parameter specifies
        whether the OS should process platform reported errors as informational
        errors as opposed to service actionable events.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_65017" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>When 
                <emphasis>ibm,get-system-parameter</emphasis> is called specifying the
                Platform Error Classification system parameter, the platform must return
                a value of 
                <emphasis role="bold"><literal>&#8220;1&#8221;</literal></emphasis> if all errors returned in 
                <emphasis>event-scan</emphasis>, 
                <emphasis>check-exception</emphasis>, 
                <emphasis>rtas-last-error</emphasis> and 
                <emphasis>ibm,slot-error-detail</emphasis> calls should be treated as
                informational errors in the sense that they not be reported by service
                applications as service actionable events and otherwise must return a
                value of 
                <emphasis role="bold"><literal>&#8220;0&#8221;</literal></emphasis>.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
        <para>
        <emphasis role="bold">Programming Note:</emphasis> Service applications within an
        operating system may obtain information about platform errors and take
        service actions (such as reporting the errors to a call center or other
        error aggregation point) based on errors logged. Service applications
        running in multiple partitions, each receiving platform error events, may
        all report the same error to an aggregation point causing duplicated
        error reports. To eliminate this duplication, a platform might choose to
        log errors to only one partition in a system. That, however, would leave
        an incomplete error record in individual partition and eliminate
        notifications that each partition OS should be aware of (such as EPOW
        events).</para>
        <para>To allow platform errors to be reported to an OS, but prevent the
        forwarding of the errors as service actionable events to an error
        aggregation point, the Platform Error Classification system parameter may
        be set to a value of 1.</para>
        <para>The OS should not change how it logs an error based on this
        parameter, nor should the OS change any error severity associated with
        the log based on the parameter. Rather it is left to service applications
        to query the system parameter and take actions based on it.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_93780">
        <title>Firmware Boot Options</title>
        
        <para>The Firmware Boot Options system parameter allows specification of
        various firmware boot settings.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_93780" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>When <emphasis>ibm,get-system-parameter</emphasis> is called specifying the
                Firmware Boot Options system parameter, the first two bytes of the value
                returned must be binary and must contain the full length of the parameter
                data, including the length of the NULL, and the field following length
                field must be a variable of the form: &#8220;keyword&#8221; followed by
                &#8220;=&#8221; followed by &#8220;value&#8221; and terminated by a
                semicolon (&#8220;;&#8221;), where the contents of &#8220;value&#8221;
                must be an ASCII printable character string.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_93780" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>When <emphasis>ibm,set-system-parameter</emphasis> is 
                called specifying the
                Firmware Boot Options system parameter, the first two bytes of the buffer
                must be binary and must contain the full length of the parameter data,
                including the length of the NULL, and the field following length field
                must be a variable of the form: &#8220;keyword&#8221; followed by
                &#8220;=&#8221; followed by &#8220;value&#8221; and terminated by a
                semicolon (&#8220;;&#8221;), where the contents of &#8220;value&#8221;
                must be an ASCII printable character string, and if the caller is not
                authorized to adjust at least one of the specified keywords, the call
                must return with a status of -9002.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_93780" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para>Keyword and values for the Firmware
                Boot Options parameter must be as defined in 
                <xref linkend="dbdoclet.50569332_60897" />.</para>
          
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_60897">
                  <title>Firmware Boot Options System Parameter Keywords and
                  Values</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">Keyword</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Permitted Values</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Definition</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>PlatformBootSpeed</para>
                        </entry>
                        <entry>
                          <para>fast, slow</para>
                        </entry>
                        <entry>
                          <para>fast: The platform will perform a minimal set of hardware
                          tests before loading the OS.</para>
                          <para>slow: The platform will perform a comprehensive set of
                          hardware tests before loading the OS.</para>
                          <para>Absence of the keyword implies the platform does not
                          support an alterable boot speed.</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_93122">
        <title>Platform Processor Diagnostics Options</title>
        
        <para>The platform-processor-diagnostics-run-mode system parameter allows
        the operating system to query or control how platform run-time processor
        diagnostics are executed by the platform. Provision is made by this
        parameter for the platform to execute run-time diagnostic tests to verify
        various processor functions. These diagnostics tests typically would be
        performed by the hypervisor against each processor in the system.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_93122" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para>When 
                <emphasis>ibm,get-system-parameter</emphasis> is called with the
                platform-processor-diagnostics-run-mode token, the platform must return a
                one-byte parameter indicating the current run-mode of platform processor
                diagnostics as one of the following:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>0 = disabled: indicates that the platform will not run processor
                    run-time diagnostics.</para>
                  </listitem>
          
                  <listitem>
                    <para>1 = staggered: indicates that the platform is set to run
                    processor diagnostics on each processor on a periodic basis, but not
                    attempt to schedule the tests for all processors at the same time. The
                    frequency at which the tests will run are defined by the platform.</para>
                  </listitem>
          
                  <listitem>
                    <para>2 = immediate: indicates that the platform is currently in the
                    processor of running diagnostics against the processors in a system on a
                    non-staggered basis, either as a result of an &#8220;immediate&#8221; or
                    &#8220;periodic&#8221; setting.</para>
                  </listitem>
          
                  <listitem>
                    <para>3 = periodic: indicates that the platform is scheduled to run
                    diagnostics against all the processors in the system at a specific time
                    scheduled by the platform.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_93122" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para>When 
                <emphasis>ibm,set-system-parameter</emphasis> is called specifying the
                platform-processor-diagnostics-run-mode token, the one-byte parameter
                passed must indicate the run-mode of platform periodic diagnostics
                desired as one of the following:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>0 = disabled: indicates that the platform should not run any
                    processor run-time diagnostics. Any currently running diagnostics will be
                    terminated.</para>
                  </listitem>
          
                  <listitem>
                    <para>1 = staggered: indicates that the platform should run
                    diagnostics periodically against each processor in the system, but not
                    attempt to schedule the tests for all processors at the same time. The
                    frequency at which the tests will run are defined by the platform.</para>
                  </listitem>
          
                  <listitem>
                    <para>2 = immediate: indicates that the platform should immediately
                    begin the process of running processor diagnostics on all of the
                    processors in the system, This setting only temporarily overrides the
                    setting of &#8220;disabled&#8221;, &#8220;staggered&#8221; or
                    &#8220;periodic&#8221; and the platform will revert to the last setting
                    of &#8220;disabled&#8221;, &#8220;staggered&#8221; or
                    &#8220;periodic&#8221; once the immediately run diagnostics are
                    complete.</para>
                  </listitem>
                </orderedlist>		      
              </listitem>
         	</varlistentry>
        </variablelist>
        
        <para>
        <emphasis role="bold">Implementation Notes:</emphasis> To prevent conflicts in the
        setting of the run-mode, the platform should only support this parameter
        for one partition in a running system. The options may also be set by the
        platform. The last value set will take precedent over any previous
        settings.</para>
      </section>
      
      <section xml:id="dbdoclet.50569332_64713">
        <title>Processor Module Information</title>
        
        <para>The Processor Module Information system parameter allows
        transferring of certain processor module information from the platform to
        the OS. The information in the parameter is global for the platform and
        encompasses all resources on the platform, not just those available to
        the partition, and the 
        <emphasis>ibm,get-system-parameter</emphasis> will never return a 
        <emphasis>Status</emphasis> of -9002 (Not Authorized). This parameter is
        read-only.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_64713" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option with the System Parameters
                option:</emphasis> If the platform supports the Processor Module
                Information system parameter, then it must provide the following
                information in the parameter, and the information returned for every
                partition must be the same, with all the resources of the platform
                encompassed:</para>
                <para>2 byte binary number (N) of module types followed by N module
                specifiers of the form:</para>
                <para>2 byte binary number (M) of sockets of this module type</para>
                <para>2 byte binary number (L) of chips per this module type</para>
                <para>2 byte binary number (K) of cores per chip in this module
                type.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_64713" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option with the System Parameters
                option:</emphasis> For the Processor Module Information system parameter,
                the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call must never return
                a 
                <emphasis>Status</emphasis> of -9002 (Not Authorized), and the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS call must always return
                a Status of -9002 (Setting not allowed/authorized).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_63170">
        <title>Cede Latency Settings Information</title>
        
        <para>The Cede Latency Settings Information system parameter informs the
        OS of the maximum latency to wake up from the various platform supported
        processor sleep states that it might employ for idle processors. The
        information in the parameter is global for the platform and encompasses
        all processors on the platform, and the 
        <emphasis>ibm,get-system-parameter</emphasis> will never return a 
        <emphasis>Status</emphasis> of -9002 (Not Authorized). This parameter is
        read-only. As the architecture evolves, the number of fields per record
        are likely to increase, calling software should be written to handle
        fewer fields (should it find itself running on a platform supporting an
        older version of the architecture) and ignore additional fields (should
        it find itself running on a platform supporting a newer version of the
        architecture). Due to partition migration, the support for the cede
        latency setting system parameter, the number of supported cede latency
        settings (and thus the number of reported records) and the number of
        fields reported per record might change from call to call; calling
        software should be written to handle this variability</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_63170" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PEM option with the System Parameters
                option:</emphasis> If the platform supports the cede latency settings
                information system parameter it must provide the following information in
                the NULL terminated parameter string:</para>
                
                <orderedlist numeration="loweralpha">		      
                  <listitem>
                    <para>The first byte is the binary length &#8220;N&#8221; of each cede
                    latency setting record minus one (zero indicates a length of 1
                    byte)</para>
                  </listitem>
          
                  <listitem>
                    <para>For each supported cede latency setting a cede latency setting
                    record consisting of: The first &#8220;N&#8221; bytes of 
                    <xref linkend="dbdoclet.50569332_64326" />.</para>
                  </listitem>
                </orderedlist>		      
                
                <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64326">
                  <title>Byte definitions within a cede latency setting
                  record</title>
                  <tgroup cols="4">
                    <colspec colname="c1" colwidth="25*" />
                    <colspec colname="c2" colwidth="25*" />
                    <colspec colname="c3" colwidth="25*" />
                    <colspec colname="c4" colwidth="25*" />
                    <thead>
                      <row>
                        <entry>
                          <para>
                            <emphasis role="bold">Order of fields within a
                            record</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Field Length</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Values</emphasis>
                          </para>
                        </entry>
                        <entry>
                          <para>
                            <emphasis role="bold">Comments</emphasis>
                          </para>
                        </entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry>
                          <para>Cede Latency Specifier Value</para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                        <entry>
                          <para>Binary Values 0-255</para>
                        </entry>
                        <entry>
                          <para>Records in ascending cede latency specifier value order
                          with no holes.</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Maximum wakeup latency in time base ticks</para>
                        </entry>
                        <entry>
                          <para>8</para>
                        </entry>
                        <entry>
                          <para>0x0000000000000000 - 0xFFFFFFFFFFFFFFFF</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                      </row>
                      <row>
                        <entry>
                          <para>Responsive to external interrupts</para>
                        </entry>
                        <entry>
                          <para>1</para>
                        </entry>
                        <entry>
                          <para>Binary True/False</para>
                        </entry>
                        <entry>
                          <para>&#160;</para>
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_63170" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PEM option with the System Parameters
                option:</emphasis> For the cede latency specifier system parameter, the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call must never return
                a 
                <emphasis>Status</emphasis> of -9002 (Not Authorized), and the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS call must always return
                a 
                <emphasis>Status</emphasis> of -9002 (Setting not
                allowed/authorized).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_81972">
        <title>Target Active Memory Compression Factor</title>
        
        <para>The target active memory compression factor system parameter
        informs the OS of the target memory capacity increase the customer
        expects to achieve due to active memory compression. The factor is
        expressed in whole percentage with the minimum value of 100 and the
        maximum value of 1000.</para>
        <para>The 
        <emphasis>ibm,get-system-parameter</emphasis> for parameter token 46 will
        never return a 
        <emphasis>Status</emphasis> of -9002 (Not Authorized). This parameter is
        read-only.</para>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81972" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Active Memory Compression option with the System
                Parameters option:</emphasis> For the Target Active Memory Compression
                Factor system parameter, the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS call must never return
                a Status of -9002 (Not Authorized).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81972" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Active Memory Compression option with the System
                Parameters option:</emphasis> If the Active Memory Compression option is
                enabled for the partition, the platform must provide in response to the 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 46 the
                two byte target active memory compression factor in binary format in the
                range (0x0064 -- 0x03E8) (equivalent to 100 -- 1000 decimal).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81972" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Active Memory Compression option with the System
                Parameters option:</emphasis> If the Active Memory Compression option is
                disabled for the system/partition, the platform must provide in response
                to the 
                <emphasis role="bold">ibm,get-system-parameter</emphasis> for parameter token 46 the
                two byte value 0x0000.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_81972" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Active Memory Compression option with the System
                Parameters option:</emphasis> For the target active memory compression
                factor system parameter, the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS call must always return
                a Status of -9002 (Setting not allowed/authorized).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
  
      </section>
      
      <section xml:id="dbdoclet.50569332_57301">
        <title>Performance Boost Modes Vector</title>
        
        <para>A variety of platform dependent configuration modes might result in
        a boost in platform computational capacity. The 
        <emphasis>ibm,get-system-parameter</emphasis> through the performance
        boost modes vector system parameter communicates to the client program
        which of these modes are available on the specific platform, which of
        these modes the client program may enable/disable, and which ones are
        active.</para>
        <para>The performance boost mode vectors are 32 bytes (256 bits) long.
        Each bit position within the performance boost mode vector corresponds to
        a specific function as specified in 
        <xref linkend="dbdoclet.50569332_45128" />. The first defined boost mode
        is assigned to the highest order bit position. As new boost modes are
        defined, they are assigned to sequential lower order vector bit
        positions.</para>
        <para>Given that the second version of the vector from the 
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call (specifying which
        modes may be enabled/disabled by the client program) is non-zero, the
        platform supports calling the 
        <emphasis>ibm,set-system-parameter</emphasis> RTAS call specifying the
        performance boost modes vector token. The 
        <emphasis>ibm,set-system-parameter</emphasis> RTAS call specifying the
        performance boost modes vector token takes a single vector as
        input.</para>
  
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_45128">
          <title>Performance Boost Modes Vector Bits
          Definitions</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="50*" />
            <colspec colname="c2" colwidth="50*" />
            <thead>
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Bit Position (1 based
                    ordinal)</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Definition</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Extended Cache Option</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>2-- 256</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
  
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> The platform
                must implement the System Parameters option.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> The 96 byte
                report returned by 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 47 must
                consist of three 32 byte bit vectors as defined by 
                <xref linkend="dbdoclet.50569332_45128" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> The first 32
                byte bit vector returned by 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 47 must
                contain 1s in the bit positions define by 
                <xref linkend="dbdoclet.50569332_45128" /> for the performance boost modes
                that are both supported by the platform and authorized for the caller (by
                means outside of the scope of LoPAR).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> The second 32
                byte bit vector returned by 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 47 must
                contain 1s in the bit positions define by 
                <xref linkend="dbdoclet.50569332_45128" /> for the performance boost modes
                that are both represented in the first vector and may be enabled/disabled
                by the caller through the 
                <emphasis>ibm,set-system-parameter</emphasis> using parameter token
                47.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> The third 32
                byte bit vector returned by 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 47 must
                contain 1s in the bit positions define by 
                <xref linkend="dbdoclet.50569332_45128" /> for the performance boost modes
                that are both represented in the first vector and are enabled either by
                default or by the caller through the 
                <emphasis>ibm,set-system-parameter</emphasis> using parameter token
                47.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> If the 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 47
                communicated that the client program has the ability to enable/disable
                one or more of the boost modes, then the platform must support the
                performance boost modes vector token for ibm,set-system-parameter.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> If no boost
                modes can be enabled/disabled then a call to ibm,set-system-parameter
                specifying the boost modes vector token must return either:</para>
                
                <itemizedlist>		      
                  <listitem>
                    <para>&#8220;System parameter not supported&#8221; as indeed the
                    implementation need not code support for the token if no mode setting is
                    supported.</para>
                  </listitem>
                  
                  <listitem>
                    <para>&#8220;Setting not allowed/authorized&#8221; if the
                    implementation supports setting boost modes but the caller is not
                    authorized to do so.</para>
                  </listitem>
                </itemizedlist>		      
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> If any input
                vector to the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS for parameter token 47
                is a one and does not correspond to a bit that is a one in the second
                version of the vector returned by the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS for parameter token 47
                the ibm,set-system-parameter RTAS must return parameter error.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> If the
                corresponding bit that was a one in the second version of the vector
                returned by the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS for parameter token 47
                is a one in the input vector to the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS for parameter token 47
                then upon successful return that corresponding boost mode must be
                enabled.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> If the
                corresponding bit that was a one in the second version of the vector
                returned by the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS for parameter token 47
                is a zero in the input vector to the 
                <emphasis>ibm,set-system-parameter</emphasis> RTAS for parameter token 47
                then upon successful return that corresponding boost mode must be
                disabled.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> To properly
                awake from partition suspension and handle dynamic reconfiguration, the
                client program must be prepared to handle changes in the bit settings
                within the bit vectors reported by the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS for parameter token
                47.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_57301" 
            xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Performance Boost Modes option:</emphasis> Since it is
                expected that bit positions define by 
                <xref linkend="dbdoclet.50569332_45128" /> will expand over time, to avoid
                firmware level compatibility issues, the client program must ignore bit
                settings within the bit vectors reported by the 
                <emphasis>ibm,get-system-parameter</emphasis> RTAS for parameter token 47
                beyond those defined when the client pr gram was designed.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
                
      </section>
      
      <section xml:id="sec_tlb_block_invalidate">
        <title>TLB Block Invalidate Characteristics</title>
        
        <para>The Block Invalidate option allows for the removal of multiple page table entries with a single platform wide TLB invalidate
        sequence, providing significantly improved performance when removing a virtual memory object. The size of
        the block (the number of consecutive virtual memory pages) that is processed by a single TLB invalidate sequence is
        implementation dependent. This block size might also be dependent upon the page sizes of the TLB entries. This block
        size represents the upper bound of the number of pages that may be processed in a single operation as for example a
        single call to H_BLOCK_REMOVE. This system parameter provides the client code the characteristics of the implementation’s
        TLB invalidate operations. The TLB Invalidate Characteristics return string is a variable length series of
        bytes which contains one or more TLB Block Invalidate Specifiers as defined in Table 108‚ “TLB Block Invalidate
        Characteristics Specifier Format‚” on page 253. If the implementation invalidates different sized blocks for different
        page size encodings, there will be multiple “TLB Block Invalidate Characteristics Specifiers” within the returned
        string.</para>
        
        <table xml:id="table_tlb_block_invalidate_format">
          <title>TLB Block Invalidate Characteristics Specifier Format</title>
          <tgroup cols="3">
            <colspec colname="c1" colwidth="10*" align="center" />
            <colspec colname="c2" colwidth="15*" align="center" />
            <colspec colname="c3" colwidth="75*" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>Byte Offset</para>
                </entry>
                <entry>
                  <para>Bit Number in Byte</para>
                </entry>
                <entry align="center">
                  <para>Description</para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>0 - 7</para>
                </entry>
                <entry>
                  <para>LOG base 2 of the TLB invalidate block size being specified</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>0 - 7</para>
                </entry>
                <entry>
                  <para>Number of page sizes (N) that are supported for the specified TLB invalidate block size</para>
                </entry>
              </row>
              <row>
                <entry morerows="2">
                  <para>2 - (N+1)</para>
                </entry>
                <entry>
                  <para>0</para>
                </entry>
                <entry>
                  <para>PTE “L” bit:<?linebreak?>
                  0 = 4K page in a segment who’s base page size is 4K<?linebreak?>
                  1 = page size and segment base size per bits 2 - 7</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Reserved</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>2 - 7</para>
                </entry>
                <entry>
                  <para>Encoded segment base page size and actual page size per 
                  <xref linkend="dbdoclet.50569387_99718" /> Book IVa</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_tlb_block_invalidate" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Block Invalidate option with the 
                System Parameters option:</emphasis> For the Block Invalidate system
                parameter, the <emphasis>ibm,get-system-parameter</emphasis> RTAS call must 
                never return a Status of -9002 (Not Authorized).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_tlb_block_invalidate" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Block Invalidate option with the 
                System Parameters option:</emphasis> If the Block Invalidate option 
                is enabled for the partition, the platform must provide in response 
                to the <emphasis>ibm,get-system-parameter</emphasis> for
                parameter token 50 the one or more TLB Block Invalidate 
                Specifiers for the calling partition as described in
                <xref linkend="table_tlb_block_invalidate_format" />.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_tlb_block_invalidate" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Block Invalidate option with the 
                System Parameters option:</emphasis> If the Block Invalidate
                option is disabled for the system/partition, the platform must 
                provide in response to the <emphasis>ibm,get-system-parameter</emphasis> 
                for parameter token 50 the two byte value 0x0000.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_tlb_block_invalidate" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the Block Invalidate option with the 
                System Parameters option:</emphasis> For the Block Invalidate
                system parameter, the <emphasis>ibm,get-system-parameter</emphasis>RTAS call must 
                always return a Status of -9002 (Setting not allowed/authorized).</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>
      
      <section xml:id="sec_energy_management_tuning_parameters">
        <title>Energy Management Tuning Parameters (EMTP)</title>
        
        <para>The energy management tuning parameters are reported. Each parameter occupies 
        its own 8 byte self-defining entry. As many energy management tuning parameter entries 
        as are supported by the system are reported, subject to the limitation of the buffer 
        length. Each reported parameter entry is formatted per 
        <xref linkend="table_format_emtp_entry" />.</para>
        
        <table xml:id="table_format_emtp_entry">
          <title>Format of the Energy Management Tuning Parameter Entry</title>
          <tgroup cols="8">
            <colspec colname="c1" colwidth="12*" align="center" />
            <colspec colname="c2" colwidth="12*" align="center" />
            <colspec colname="c3" colwidth="12*" align="center" />
            <colspec colname="c4" colwidth="12*" align="center" />
            <colspec colname="c5" colwidth="12*" align="center" />
            <colspec colname="c6" colwidth="12*" align="center" />
            <colspec colname="c7" colwidth="12*" align="center" />
            <colspec colname="c8" colwidth="12*" align="center" />
            <thead valign="middle">
              <row>
                <entry><para>Byte 0</para></entry>
                <entry><para>Byte 1</para></entry>
                <entry><para>Byte 2</para></entry>
                <entry><para>Byte 3</para></entry>
                <entry><para>Byte 4</para></entry>
                <entry><para>Byte 5</para></entry>
                <entry><para>Byte 6</para></entry>
                <entry><para>Byte 7</para></entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>Parameter Identifier<?linebreak?>See <xref linkend="table_definition_emtp_parms" /> 
                  for definition values.</para>
                </entry>
                <entry>
                  <para>Parameter Units<?linebreak?>See <xref linkend="table_definition_emtp_parm_unit_vals" /> 
                  for definition values.</para>
                </entry>
                <entry namest="c3" nameend="c4">
                  <para>Current<?linebreak?>Parameter Value</para>
                </entry>
                <entry namest="c5" nameend="c6">
                  <para>Minimum<?linebreak?>Parameter Value</para>
                </entry>
                <entry namest="c7" nameend="c8">
                  <para>Maximum<?linebreak?>Parameter Value</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table xml:id="table_definition_emtp_parms">
          <title>Definition of the Energy Management Tuning Parameters</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="20*" align="center" />
            <colspec colname="c2" colwidth="80*" />
            <thead valign="middle">
              <row>
                <entry><para>Parameter ID</para></entry>
                <entry align="center"><para>Definition</para></entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry><para>0x01</para></entry>
                <entry><para>Utilization threshold for increasing frequency</para></entry>
              </row>
              <row>
                <entry><para>0x02</para></entry>
                <entry><para>Utilization threshold for decreasing frequency</para></entry>
              </row>
              <row>
                <entry><para>0x03</para></entry>
                <entry><para>Number of samples for computing utilization statistics</para></entry>
              </row>
              <row>
                <entry><para>0x04</para></entry>
                <entry><para>Step size for going up in frequency</para></entry>
              </row>
              <row>
                <entry><para>0x05</para></entry>
                <entry><para>Step size for going down in frequency</para></entry>
              </row>
              <row>
                <entry><para>0x06</para></entry>
                <entry><para>Delta percentage for determining active cores</para></entry>
              </row>
              <row>
                <entry><para>0x07</para></entry>
                <entry><para>Utilization threshold to determine active cores with slack</para></entry>
              </row>
              <row>
                <entry><para>0x08</para></entry>
                <entry><para>Enable/Disable frequency delta between cores</para></entry>
              </row>
              <row>
                <entry><para>0x09</para></entry>
                <entry><para>Maximum frequency delta between cores</para></entry>
              </row>
              <row>
                <entry namest="c1" nameend="c2"><para>&#160;</para></entry>
              </row>
              <row>
                <entry><para>0x50</para></entry>
                <entry><para>Idle Power Saver enabled/disabled</para></entry>
              </row>
              <row>
                <entry><para>0x51</para></entry>
                <entry><para>Delay time to enter Idle Power Saver</para></entry>
              </row>
              <row>
                <entry><para>0x52</para></entry>
                <entry><para>Utilization threshold to enter Idle Power Saver</para></entry>
              </row>
              <row>
                <entry><para>0x53</para></entry>
                <entry><para>Delay time to exit Idle Power Saver</para></entry>
              </row>
              <row>
                <entry><para>0x54</para></entry>
                <entry><para>Utilization threshold to exit Idle Power Saver</para></entry>
              </row>
              <row>
                <entry><para>&#160;</para></entry>
                <entry>
                  <para>All other Parameter ID Values are reserved, should calling software 
                  encounter a parameter id value which was reserved at the time it was 
                  written, it shall ignore the specific entry, and only that entry.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table xml:id="table_definition_emtp_parm_unit_vals">
          <title>Definition of the Energy Management Parameter Unit Values</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="20*" align="center" />
            <colspec colname="c2" colwidth="80*" />
            <thead valign="middle">
              <row>
                <entry><para>Parameter Units</para></entry>
                <entry align="center"><para>Definition</para></entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry><para>0x00</para></entry>
                <entry><para>Parameter can only be either 1 (enabled) or 0 (disabled)</para></entry>
              </row>
              <row>
                <entry><para>0x01</para></entry>
                <entry><para>Parameter is time in seconds i.e. 10 = 10 seconds</para></entry>
              </row>
              <row>
                <entry><para>0x02</para></entry>
                <entry><para>Parameter is a percentage i.e. 10 = 10%</para></entry>
              </row>
              <row>
                <entry><para>0x03</para></entry>
                <entry><para>Parameter is in 10ths of a percent i.e. 15 = 1.5%</para></entry>
              </row>
              <row>
                <entry><para>0x04</para></entry>
                <entry><para>Parameter is an integer</para></entry>
              </row>
              <row>
                <entry><para>&#160;</para></entry>
                <entry>
                  <para>All other Parameter Unit Values are reserved, should calling software 
                  encounter a parameter unit value which was reserved at the time it was 
                  written, it shall ignore the specific entry, and only that entry.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_energy_management_tuning_parameters" 
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EMTP option with the System Parameters option:</emphasis>
                For the EMTP system parameter, the <emphasis>ibm,get-system-parameter</emphasis> RTAS call 
                must never return a Status of -9002 (Not Authorized).</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_energy_management_tuning_parameters" 
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EMTP option with the System Parameters option:</emphasis>
                If the EMTP option is enabled for the partition, the platform must provide in response to the 
                <emphasis>ibm,get-system-parameter</emphasis> for parameter token 52 the Energy Management 
                Tuning Parameters for the calling system as described in this section.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_energy_management_tuning_parameters" 
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EMTP option with the System Parameters option:</emphasis>
                If the EMTP option is disabled for the system/partition, the platform must provide in 
                response to the <emphasis>ibm,get-system-parameter</emphasis> for parameter token 52 the 
                two byte value 0x0000.</para>
              </listitem>
         	</varlistentry>
         	
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_energy_management_tuning_parameters" 
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the EMTP option with the System Parameters option:</emphasis>
                For the EMTP system parameter, the <emphasis>ibm,set-system-parameter</emphasis> RTAS call 
                must always return a Status of -9002 (Setting not allowed/authorized).</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>
          
  </section>

  <xi:include href="sec_rtas_get_indices.xml"/>
    
</chapter>
