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

24925 lines
1.0 MiB
Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters!

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

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section 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="dbdoclet.50569333_15433" />.</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><emphasis>nvram-fetch</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>nvram-store</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569333_15433" />.</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="dbdoclet.50569327_71913" />.</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><emphasis>get-time-of-day</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>set-time-of-day</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569327_71913" /> 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><emphasis>set-time-for-power-on</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>event-scan</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_22801" />. 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="dbdoclet.50569337_82470" /> 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><emphasis>check-exception</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Source of Interrupt</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Value of &#8220;Additional
Information&#8221; Variable</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_22801" />. 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="dbdoclet.50569337_82470" /> 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="dbdoclet.50569368_91814" />.</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><emphasis>rtas-last-error</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_22801" />. 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><emphasis>ibm,platform-dump</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center"/>
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Discussion</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Discussion</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Discussion</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569328_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*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Bit</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569330_49381" /> 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="dbdoclet.50569368_43390" />) 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><emphasis>ibm,read-pci-config</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,write-pci-config</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569368_41461" />:</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><emphasis>display-character</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="8*" align="center" />
<colspec colname="c3" colwidth="8*" align="center" />
<colspec colname="c4" colwidth="8*" align="center" />
<colspec colname="c5" colwidth="8*" align="center" />
<colspec colname="c6" colwidth="8*" align="center" />
<colspec colname="c7" colwidth="8*" align="center" />
<colspec colname="c8" colwidth="8*" align="center" />
<colspec colname="c9" colwidth="8*" align="center" />
<colspec colname="c10" colwidth="8*" align="center" />
<colspec colname="c11" colwidth="8*" align="center" />
<colspec colname="c12" colwidth="8*" align="center" />
<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 valign="middle" >
<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><emphasis>set-indicator</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="6*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="6*" align="center" />
<colspec colname="c6" colwidth="18*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="18*" />
<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 align="center" >
<para>
<emphasis role="bold">Examples/Comments</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569327_91037" />.</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="dbdoclet.50569327_91037" />.</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="dbdoclet.50569342_61130" /> 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="dbdoclet.50569347_31867" /> and
<xref linkend="dbdoclet.50569342_42695" /> 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="dbdoclet.50569342_61130" /> 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="dbdoclet.50569347_31867" />.</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="dbdoclet.50569347_31867" /> and
<xref linkend="dbdoclet.50569342_42695" /> 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="dbdoclet.50569347_31867" />.</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="dbdoclet.50569347_31867" /> and
<xref linkend="dbdoclet.50569342_42695" /> 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
<superscript>ibm,interrupt-server#-size</superscript>) - 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*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569342_75822" />)</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="dbdoclet.50569337_17513" />). 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*" align="center" />
<colspec colname="c2" colwidth="6*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="6*" align="center" />
<colspec colname="c5" colwidth="14*" align="center" />
<colspec colname="c6" colwidth="20*" align="center" />
<colspec colname="c7" colwidth="20*" />
<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 align="center" >
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569342_75822" /> and
<xref linkend="dbdoclet.50569342_85040" />.</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="dbdoclet.50569347_31867" />.</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="dbdoclet.50569347_31867" />.</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*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">token</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">maxindex</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">value</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569341_35066" />. 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*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Status</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569368_41461" />).</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>
<itemizedlist>
<listitem>
<para>For legacy compatibility mode, the index value for global interrupt
queue control state sensor (9005) must be
(2<superscript>ibm,interrupt-server#-size</superscript>) - 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>
<listitem>
<para>For exploitation compatibility mode, the index value must be 0,
which is the only supported global server index in exploitation
compatibility mode.</para>
</listitem>
</itemizedlist>
</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><emphasis>set-power-level</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>get-power-level</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Bit</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Event</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,power-off-ups</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_81250" />.</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="dbdoclet.50569333_25869" /> 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><emphasis>system-reboot</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center" >
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569344_48079" /> 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><emphasis>ibm,update-flash-64-and-reboot</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<thead>
<row>
<entry>
<para>Length of
<emphasis>Block_list</emphasis> in bytes</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569368_41461" />) 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*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>VER</para>
</entry>
<entry>
<para>Length of
<emphasis>Block_list</emphasis> in bytes</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,manage-flash-image</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,validate-flash-image</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Token</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,activate-firmware</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569340_88608" />)</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="dbdoclet.50569340_88608" />)</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><emphasis>stop-self</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>start-cpu</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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>
<para>3: Not enough resources available to start CPU</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis role="bold">Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569329_35915" /> 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*" align="center" />
<colspec colname="c2" colwidth="16*" align="center" />
<colspec colname="c3" colwidth="16*" />
<colspec colname="c4" colwidth="16*" align="center" />
<colspec colname="c5" colwidth="16*" align="center" />
<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 align="center">
<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 align="center">
<para>
<emphasis role="bold">Initial Value upon start by
start-cpu</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>query-cpu-stopped-state</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,os-term</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<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 valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<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 valign="middle" >
<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="dbdoclet.50569344_75733" />.</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><emphasis>ibm,get-xive</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript></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="dbdoclet.50569344_35543" />.</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><emphasis>ibm,set-xive</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript></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="dbdoclet.50569344_77100" />.</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="dbdoclet.50569344_77100" />.</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><emphasis>ibm,int-off</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569344_77846" />.</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="dbdoclet.50569344_77100" />.</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><emphasis>ibm,int-on</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569331_33067" /> 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="dbdoclet.50569331_33067" />.</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*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569331_84312" />).</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="dbdoclet.50569368_13649" />.</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><emphasis>ibm,query-interrupt-source-number</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569381_46906" />, 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*" align="center" />
<colspec colname="c2" colwidth="14*" align="center" />
<colspec colname="c3" colwidth="14*" align="center" />
<colspec colname="c4" colwidth="14*" align="center" />
<colspec colname="c5" colwidth="14*" align="center" />
<colspec colname="c6" colwidth="14*" align="center" />
<colspec colname="c7" colwidth="14*" align="center" />
<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>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<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>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<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>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<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>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<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>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<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*" align="center" />
<colspec colname="c2" colwidth="17*" align="center" />
<colspec colname="c3" colwidth="11*" align="center" />
<colspec colname="c4" colwidth="11*" align="center" />
<colspec colname="c5" colwidth="11*" align="center" />
<colspec colname="c6" colwidth="11*" align="center" />
<colspec colname="c7" colwidth="11*" align="center" />
<colspec colname="c8" colwidth="11*" align="center" />
<colspec colname="c9" colwidth="11*" align="center" />
<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="dbdoclet.50569330_40070" />.</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><emphasis>ibm,set-eeh-option</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569330_49770" />).</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><emphasis>ibm,set-slot-reset</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569330_40070" />.</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><emphasis>ibm,read-slot-reset-state2</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569368_41461" />).</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:26 - Reserved</para>
<para>&#160;</para>
<para>Bit 27 - XIVE ESB Reset Status (valid for XIVE Exploitation mode only)</para>
<para>Bit 27 = 0: XIVE ESBs for this PE were not reset as a result of the
platform transition for PE Reset State of 2.</para>
<para>Bit 27 = 1: XIVE ESBs for this PE were reset as a result of the
platform transition for PE Reset State of 2. The ESB state for each
interrupt must be reinitialized prior to recovering the device.</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="dbdoclet.50569330_34831" /> 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><emphasis>ibm,get-config-addr-info2</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="15*" align="center" />
<colspec colname="c2" colwidth="30*" align="center" />
<colspec colname="c3" colwidth="55*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">
<emphasis>Function</emphasis> Input</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">
<emphasis>Info</emphasis> Output</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_22801" />. 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><emphasis>ibm,slot-error-detail</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_22801" />.</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="40*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="40*" />
<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 align="center">
<para>
<emphasis role="bold">Register</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,configure-bridge</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,configure-pe</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569335_13568" />).</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><emphasis>ibm,open-errinjct</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,close-errinjct</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,errinjct</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569368_41461" />) 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="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Errinjct-token-name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Errinjct function</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Errinjct-token-name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Errinjct work buffer format</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="15*" align="center" />
<colspec colname="c2" colwidth="30*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="27*" align="center" />
<colspec colname="c5" colwidth="27*" align="center" />
<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 valign="middle" >
<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="dbdoclet.50569330_20501" /> 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="dbdoclet.50569337_21249" />. 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><emphasis>ibm,nmi-register or ibm,nmi-register-2</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="dbdoclet.50569337_21249" />) 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="dbdoclet.50569337_37595" />) 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="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Option Number</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Implementation Option for handling an
unsafe processor.</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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><emphasis>ibm,nmi-interlock</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" align="center" />
<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 valign="middle" >
<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, 3</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_<?linebreak?>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-<?linebreak?>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-<?linebreak?>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, 4</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>1</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>1</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>2</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>1</para>
</entry>
</row>
<row>
<entry>
<para>56</para>
</entry>
<entry>
<para>NVDIMM Protection State</para>
</entry>
<entry>
<para>Controls whether or not the platform will copy the contents of a partition's
NVDIMMs to flash on EPOW loss-of-power and other normal power off events.</para>
</entry>
<entry>
<para>One byte decimal:</para>
<para>0 = disabled/disarmed</para>
<para>1 = enabled/armed</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>57</para>
</entry>
<entry>
<para>NVDIMM Encryption State</para>
</entry>
<entry>
<para>Controls whether or not the platform will encrypt the contents of
a partition's NVDIMMs.</para>
</entry>
<entry>
<para>One byte decimal:</para>
<para>0 = disabled</para>
<para>1 = enabled</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>58</para>
</entry>
<entry>
<para>NVDIMM Secure Erase Command</para>
</entry>
<entry>
<para>Sends specified commands to the platform to drive the secure
erase and verification of a partition's NVDIMMs.</para>
</entry>
<entry>
<para>One byte decimal:</para>
<para>0 = start NVDIMM secure erase</para>
<para>1 = check secure erase status</para>
</entry>
<entry>
<para>2, 5</para>
</entry>
</row>
<row>
<entry>
<para>&gt;58</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>Used by ibm,set-system-parameter; not supported for
ibm,get-system-parameter</para>
</listitem>
<listitem>
<para>The format of the SPLPAR string is beyond the scope of this
architecture. See also,
<xref linkend="dbdoclet.50569367_15730" />.</para>
</listitem>
<listitem>
<para>See <xref linkend="dbdoclet.50569382_58396" />.</para>
<para>Further parameters will be defined as required.</para>
</listitem>
<listitem>
<para>To drive an NVDIMM secure erase and verification procedure,
Software must 'start' the erase procedure and then continue with
repeated 'check' commands for up to a time period required by
the platform. The repeated 'check' commands signal the platform
to continually monitor the status of the ongoing erase operation
which must continue until either the partition receives an
'NVDIMM status change' event notification via RTAS check-exception
or the time period is exhausted.</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><emphasis>ibm,get-system-parameter</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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>
<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: 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>
</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><emphasis>ibm,set-system-parameter</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<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 align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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>
<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: 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>
</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="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field Number</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="27*" />
<colspec colname="c5" colwidth="27*" />
<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 align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Format</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="27*" />
<colspec colname="c5" colwidth="27*" />
<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 align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Format</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="35*" />
<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 align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Keyword</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Permitted Values</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Keyword</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Permitted Values</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<colspec colname="c4" colwidth="25*" align="center" />
<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 valign="middle" >
<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*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<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 valign="middle" >
<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"/>
<xi:include href="sec_rtas_set_dynamic_indicator.xml"/>
<xi:include href="sec_rtas_get_dynamic_sensor_state.xml"/>
<xi:include href="sec_rtas_get_vpd.xml"/>
<xi:include href="sec_rtas_manage_storage_preservation.xml"/>
<xi:include href="sec_rtas_lpar_perftools.xml"/>
<xi:include href="sec_rtas_suspend_me.xml"/>
<xi:include href="sec_rtas_update_nodes.xml"/>
<xi:include href="sec_rtas_update_properties.xml"/>
<xi:include href="sec_rtas_configure_kernel_dump.xml"/>
<xi:include href="sec_rtas_dma_window.xml"/>
</section>
Reference in New Issue View Git Blame Copy Permalink