systemsoftware
/
Linux-Architecture-Reference
35
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 '0f5cdb35f0'
${ noResults }
Linux-Architecture-Reference/LoPAR/sec_rtas_environment.xml

2439 lines
111 KiB
XML
Raw Blame History

<?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_environment">
<title>Environment</title>
<para>RTAS provides an interface definition between the OS and the firmware
provided by the platform. This chapter defines the calling conventions used
by both the OS and the platform&#8217;s RTAS firmware.</para>
<para>RTAS runs with instruction and data relocate as well as processing
exceptions disabled. To not interfere with the OS, RTAS may not cause any
exceptions, nor can it depend on any particular virtual memory
mappings.</para>
<para>All RTAS functions are invoked from the OS by calling the
<emphasis>rtas-call</emphasis> function. The address of this
function is obtained from OF when
RTAS is instantiated. See Requirement
<xref linkend="dbdoclet.50569332_37615" /> for more details. RTAS determines
what function to invoke based on the data passed into the
<emphasis>rtas-call</emphasis> function. This section describes the
mechanisms used to invoke the <emphasis>rtas-call</emphasis> function,
the machine state, register usage, resource
allocation, and the invocation requirements.</para>
<para>If the LPAR option is enabled, multiple partitions may exist, each
with its own OS instance. This requires some changes to the RTAS
environment. These changes are discussed in
<xref linkend="dbdoclet.50569344_14591" />.</para>
<section xml:id="sec_machine_state">
<title>Machine State</title>
<para>When RTAS functions are invoked, the calling processor shall have
address translations, floating point, and most other exceptions disabled
and it shall be running in privileged state.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>RTAS must be called in &#8220;real
mode,&#8221; that is, all address translation must be disabled. Bits MSR<subscript>IR</subscript> and
MSR<subscript>DR</subscript> of the MSR register must be zero.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>RTAS must be called in privileged mode, and
the MSR<subscript>PR</subscript> bit must be set to 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>RTAS must be called with external
interrupts disabled, and the MSR<subscript>EE</subscript> bit must be set to 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>RTAS must be called with trace disabled,
and the MSR<subscript>SE</subscript> and
MSR<subscript>BE</subscript> bits must be set to 0.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_30796">
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>RTAS must be
called with floating point disabled, and the
MSR<subscript>FE0</subscript>,
MSR<subscript>FE1</subscript>, and
MSR<subscript>FP</subscript> bits must be set to 0.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_20114">
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>RTAS must be called with the MSR<subscript>SF</subscript>,
(MSR<subscript>ISF</subscript>, and ASR<subscript>V</subscript>
bits if applicable on the specific processor) set
to match the mode used to instantiate RTAS (0 for
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> or 1 for
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis>) and the
LE bit set to 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>With the exception of the MSR<subscript>DR</subscript> and
MSR<subscript>RI</subscript> bits, RTAS must not change the state of the
machine by modifying the MSR.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis>rtas-call</emphasis> is entered
in a non-recoverable mode, indicated by having the
MSR<subscript>RI</subscript> bit set equal to 0, then RTAS must not enter a
recoverable mode by setting the MSR<subscript>RI</subscript> bit to 1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_machine_state"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>If called with MSR<subscript>RI</subscript> equal to 1,
then RTAS must protect its own
critical regions from recursion by setting the MSR<subscript>RI</subscript>
bit to 0 when in the critical regions.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
<orderedlist>
<listitem>
<para>If the MSR<subscript>ME</subscript> bit is left enabled, the OS&#8217;s exception
handler must be aware that RTAS might have been running and that various
processor registers might not be in the expected state for an interrupted
OS, which precludes recoverability but permit logging machine
checks.</para>
</listitem>
<listitem>
<para>There are some provisions for recursive calls to RTAS error
handling functions. Therefore, RTAS should set the MSR<subscript>RI</subscript>
bit to 0 if SRR0/SRR1 or any other RTAS resource
is in a state where information could be lost and prohibit
recovery.</para>
</listitem>
<listitem>
<para>Requirement
<xref linkend="dbdoclet.50569332_20114" /> implies that RTAS must be able
to be instantiated in 64-bit mode on platforms that can support 64-bit
execution.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec_register_usage">
<title>Register Usage</title>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_23742">
<term><emphasis role="bold">R1-<xref linkend="sec_register_usage"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Except as
required by a specific function, registers SPRG2, R0, R3 through R12,
CTR, XER, LR, and fields CR2-CR4 of the CR, RTAS must preserve all OS
visible register state.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_76112">
<term><emphasis role="bold">R1-<xref linkend="sec_register_usage"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>RTAS must not modify the DEC and registers SPRG0, SPRG1, and SPRG3.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
<orderedlist>
<listitem>
<para>RTAS is entered in real mode
(with address translation turned off). In this mode, all data accesses
are assumed to be cached in copy back mode with memory coherence
required. Since these settings may not be appropriate for all accesses,
RTAS is free to transparently use the processor specific facilities
required to access platform hardware resources. The OS machine check
handler can only depend on those registers that are required to be
unchanged (see Requirement
<xref linkend="dbdoclet.50569332_23742" />).</para>
</listitem>
<listitem>
<para>RTAS must not change the preserved registers, or must first save
them and restore the original contents before returning to the OS.</para>
</listitem>
<listitem>
<para>The SRR0-SRR1, LR, CTR, XER registers, as well as any
reservations made via the load and reserve instructions, need not be
preserved.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="dbdoclet.50569332_85757">
<title>RTAS Critical Regions</title>
<para>The OS, when using RTAS, is responsible for protecting RTAS and
devices used by RTAS from any simultaneous accesses that could corrupt
memory or device registers. Such corruption could be caused by
simultaneous execution of RTAS code, or by a device driver accessing a
control register that is also modified by RTAS. In a single processor
system, since the MSR<subscript>EE</subscript> bit is 0 when entering RTAS, a call to RTAS while
it is in execution is prevented except for the machine check handler.
This handler may need to call various RTAS services such as
<emphasis>check-exception</emphasis> or
<emphasis>system-reboot</emphasis> even if the error was detected while in
an RTAS service
<emphasis>.</emphasis></para>
<para>The OS and RTAS must co-exist on the same platform. RTAS must not
change device registers that are used by the OS, nor may the OS change
device registers on devices used by RTAS. With the advent of more and
more integration into common super parts, some of these registers may
physically reside on the same component. In this section, device implies
the collection of common registers that together perform a function. Each
device must be represented in the OF device tree.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_37615">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Except as noted in Requirement
<xref linkend="dbdoclet.50569332_53788" /> and
<xref linkend="dbdoclet.50569332_46104" />, the OS must ensure that RTAS
is not called while RTAS is in execution and that RTAS is not
simultaneously called from different processors in a multi-processor
system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Any RTAS access to device or I/O registers
specified in this document must be made in such a way as to be
transparent to the OS.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_58412">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Any device that
is used to implement the RTAS abstracted services must have the property
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> in the OF device tree.
However, if the device is only used by the
<emphasis>power-off,</emphasis> and
<emphasis>system-reboot</emphasis> calls, the property should not be set.
The
<emphasis>rtas-display-device</emphasis> must be marked with the property
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> if it is a specialized
device only to be accessed via the RTAS
<emphasis>display-character</emphasis> call and not otherwise shared with
the OS</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis>
<xref linkend="dbdoclet.50569332_79165" /> clarifies when a device should
be marked with the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property, based on whether
it has any interaction with RTAS and/or the OS (with the exception of the
calls listed in Requirement
<xref linkend="dbdoclet.50569332_37615" />).</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_79165">
<title>Use of
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis></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">&#160;</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Normal Device (1)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">rtas-display-device</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Only used by OS</para>
</entry>
<entry>
<para>not marked</para>
</entry>
<entry>
<para>N/A (2)</para>
</entry>
</row>
<row>
<entry>
<para>Only used by RTAS</para>
</entry>
<entry>
<para>marked</para>
</entry>
<entry>
<para>marked</para>
</entry>
</row>
<row>
<entry>
<para>OS and RTAS shared</para>
</entry>
<entry>
<para>marked (3)</para>
</entry>
<entry>
<para>not marked (4)</para>
</entry>
</row>
<row>
<entry>
<para>Virtual</para>
</entry>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>N/A</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<orderedlist>
<listitem>
<para>A device which is not normally to be used by the OS must meet
one of the following rules.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>It must not be included in the OF device tree.</para>
</listitem>
<listitem>
<para>It must be defined as a &#8220;reserved&#8221; device
node.</para>
</listitem>
<listitem>
<para>It must be marked with the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property in the OF device
tree.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>It is assumed that an
<emphasis>rtas-display-device</emphasis> is used by RTAS.</para>
</listitem>
<listitem>
<para>It is assumed that there are no devices other than the
<emphasis>rtas-display-device</emphasis> which are used by both RTAS and
an &#8220;unaware&#8221; OS. To allow an aware OS to share a device with
RTAS, the device should be marked.</para>
</listitem>
<listitem>
<para>It is assumed that the
<emphasis>rtas-display-device</emphasis> is used by both RTAS and the OS
(as coordinated by the OS via display-character) unless it is marked. See
also Requirement
<xref linkend="dbdoclet.50569332_54841" />.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Platforms must be designed such that
accesses to devices that are marked
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
have no side effects on other registers in the system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis> </term>
<listitem>
<para>Any OS access to devices specified as
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>
must be made in such a way as to be transparent to RTAS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis> </term>
<listitem>
<para>RTAS must not generate any exceptions (for
example, no alignment exceptions, page table walk exceptions,
etc.).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_53788">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis> </term>
<listitem>
<para>The OS machine check and soft reset handlers must be
able to call the RTAS services:</para>
<itemizedlist>
<listitem>
<para><emphasis>nvram-fetch</emphasis> </para>
</listitem>
<listitem>
<para><emphasis>nvram-store</emphasis> </para>
</listitem>
<listitem>
<para><emphasis>check-exception</emphasis> </para>
</listitem>
<listitem>
<para><emphasis>display-character</emphasis></para>
</listitem>
<listitem>
<para><emphasis>system-reboot</emphasis></para>
</listitem>
<listitem>
<para><emphasis>set-power-level(0,0)</emphasis></para>
</listitem>
<listitem>
<para><emphasis>power-off</emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold">ibm,set-eeh-option</emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold">ibm,set-slot-reset</emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold">ibm,read-slot-reset-state2</emphasis></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_46104">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_85757"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>The <emphasis>stop-self</emphasis>
service need only be serialized with calls to the
<emphasis>stop-self</emphasis>,
<emphasis>start-cpu</emphasis>, and
<emphasis>set-power-level</emphasis> services. The OS must be able to call
RTAS services on other processors while a processor is stopped or being
stopped.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
<orderedlist>
<listitem>
<para>While RTAS must not generate any exceptions, it is still
possible that a machine check interrupt may occur during the execution of
an RTAS function. In this case, the machine check handler may be entered
prior to the normal termination of the RTAS function.</para>
</listitem>
<listitem>
<para>It is permissible for the OS exception handler to make an RTAS
call as long as Requirements
<xref linkend="dbdoclet.50569332_23742" /> and
<xref linkend="dbdoclet.50569332_37615" /> are met. In particular, it is
expected that the RTAS
<emphasis>check-exception</emphasis> is called from the OS exception
handler.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec_resource_allocation_and_use">
<title>Resource Allocation and Use</title>
<para>During execution, RTAS requires memory for both code and data. This
memory may be in RAM, in a private memory area only known by the system
firmware, or in memory allocated by the OS for RTAS use. RTAS should use
this memory for its stack and any state savings. This memory is
subsequently called the &#8220;RTAS private data area.&#8221;</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_37664">
<term><emphasis role="bold">R1-<xref linkend="sec_resource_allocation_and_use"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The OS must allocate
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis>
bytes of contiguous real memory as RTAS
private
data area. This memory must be aligned on a 4096 byte boundary and may
not cross a 256 MB boundary.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_13131">
<term><emphasis role="bold">R1-<xref linkend="sec_resource_allocation_and_use"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS private data area must not be accessed by the OS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_resource_allocation_and_use"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Except for the RTAS private data area, the
argument buffer, System Memory pointed to by any reference parameter in
the argument buffer, and any other System Memory areas explicitly
permitted in this chapter, RTAS must not modify any System Memory. RTAS
may, however, modify System Memory during error recovery provided that
such modifications are transparent to the OS.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_88538">
<term><emphasis role="bold">R1-<xref linkend="sec_resource_allocation_and_use"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>RTAS calls may
not sleep in any fashion nor busy wait for more than a very short period
of time, except for
<emphasis>power-off, ibm,power-off-ups, set-power-level</emphasis> (0,0),
<emphasis>system-reboot, ibm,update-flash-64-and-reboot, and
ibm,os-term</emphasis>.</para>
<para xml:id="dbdoclet.50569332_12814">
<emphasis role="bold">Software
Implementation Note:</emphasis> An RTAS call should take the same amount of time to
perform a service that it would take the OS to perform the same function.
A specific goal is that RTAS primitives should take less than a few tens
of microseconds.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_resource_allocation_and_use"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>For RTAS calls which do not allow the
<emphasis>Status</emphasis> of -2 (Busy), there may be &#8220;rare&#8221;
instances where an anomaly may occur and the call may take longer than a
&#8220;very short period of time.&#8221; In these cases, the call must
complete within 250 microseconds. Otherwise, a hardware error response
must be given.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_16363">
<title>Instantiating RTAS</title>
<para>RTAS is instantiated by an explicit client interface service call
into OF. The OF device tree contains a property
(<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis>, under
the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node) which defines how much real memory RTAS
requires from the OS. The OS allocates
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis>
bytes of real memory, and
then invokes the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> or
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> method of the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, passing the real address of the private
data area (or zero, if
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis> is zero) as the
<emphasis>rtas-base-address</emphasis> input argument. Firmware binds RTAS
to that address, binds the addresses of devices that RTAS uses, performs
any RTAS initialization, and returns the address of the
<emphasis>rtas-call</emphasis>
function
that is appropriate.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16363"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The <emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> or
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis>
OF method
must have the arguments specified in
<xref linkend="dbdoclet.50569332_14005" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14005">
<title><emphasis role="bold"><literal>instantiate-rtas</literal></emphasis>
<emphasis role="bold"><literal>instantiate-rtas-64</literal></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 align="center">
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>In</para>
</entry>
<entry>
<para>
<emphasis>rtas-base-address</emphasis>
</para>
</entry>
<entry>
<para>Real Address of RTAS area or zero, if
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis> is zero</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>rtas-call</emphasis>
</para>
</entry>
<entry>
<para>Real address used to invoke RTAS functions</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16363"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS code bound and initialized by the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> method on a 64-bit capable platform,
must be able to handle platform resources that are accessed using 64-bit
addresses.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_39240">
<title>RTAS Device Tree Properties</title>
<para>The OF device tree contains a
<emphasis role="bold"><literal>/rtas</literal></emphasis> device node that describes the implemented RTAS
features and the output device supported by RTAS. Within this device node
are properties that describe the RTAS functions implemented by the
firmware. For every implemented RTAS function, the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node contains an OF property whose name is the
same as the RTAS function. The value of this property is the token
argument passed into the
<emphasis>rtas-call</emphasis>
function
when making that specific RTAS call. Note that some
RTAS functions are optional and some are required. This is defined in
<xref linkend="dbdoclet.50569332_20008" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39240"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The OF device tree must contain a device
node named
<emphasis role="bold"><literal>/rtas</literal></emphasis> which describes the RTAS implementation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39240"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The <emphasis role="bold"><literal>/rtas</literal></emphasis> device node must have a property for each
implemented RTAS function in
<xref linkend="dbdoclet.50569332_20008" />. The value of this property is
a token that is passed into the
<emphasis>rtas-call</emphasis>
function to
indicate which RTAS function to invoke.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20008">
<title>RTAS Tokens for Functions</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">RTAS property/function</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Required?</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Notes</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;nvram-fetch&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_96529" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>Execution time proportional to amount of data</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;nvram-store&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_57392" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>Execution time proportional to amount of data</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;get-time-of-day&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_88127" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;set-time-of-day&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_35194" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;set-time-for-power-on&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_13743" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;event-scan&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_24845" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;check-exception&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_71287" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-last-error&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_71223" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,platform-dump&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_98203" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>If the Platform Dump option is implemented</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,read-pci-config&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_59536" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="1">
<para>Required</para>
</entry>
<entry morerows="1">
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,write-pci-config&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_54555" xrefstyle="select: labelnumber" />
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;display-character&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_10053" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;set-indicator&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_32164" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>Some specific indicators are required, and some are
optional</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;get-sensor-state&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_10754" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,set-system-parameter&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_31665" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-system-parameter&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_62190" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;set-power-level&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_45884" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="1">
<para>Required for DR operations (see
<xref linkend="dbdoclet.50569342_75822" />)</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;get-power-level&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_67298" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;power-off&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_79728" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Provided for platforms with software controlled power off
capability</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,power-off-ups&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_50770" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>If there may be a platform controlled UPS.</para>
</entry>
<entry>
<para>For power off control in a platform which may have power
backed up with an Uninterruptible Power Supply (UPS).</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;system-reboot&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_50284" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,update-flash-64-and-reboot&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_77103" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,manage-flash-image&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_81833" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,validate-flash-image&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_40640" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,activate-firmware&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_28163" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;stop-self&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_68497" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="2">
<para>See Note</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;start-cpu&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_39014" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;query-cpu-stopped-state&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_81575" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,os-term&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_42118" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,exti2c&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_19739" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-xive&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_48295" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="3">
<para>Required for the PowerPC External Interrupt option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,set-xive&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_13631" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,int-off&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_95487" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,int-on&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_61000" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-connector&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569342_39636" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for all DR options</para>
</entry>
<entry>
<para>See
<xref linkend="dbdoclet.50569342_75822" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,set-eeh-option&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_27269" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="1">
<para>Required for EEH option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,set-slot-reset&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_86249" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,read-slot-reset-state&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Being replaced by</para>
<para>
<emphasis>ibm,read-slot-reset-state2</emphasis>
</para>
</entry>
<entry>
<para>See
<xref linkend="dbdoclet.50569332_87326" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,read-slot-reset-state2&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_87326" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for all platforms</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-config-addr-info2&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_68098" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required on all platforms</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,slot-error-detail&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_43482" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the EEH option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,open-errinjct&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_22302" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="2">
<para>Required for ERRINJCT option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,errinjct&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_22302" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,close-errinjct&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_22302" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,nmi-register&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_12478" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="1">
<para>Required for FWNMI option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,nmi-interlock&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_12478" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-bridge&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_65423" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the EEH option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-pe&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_45262" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the EEH option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-indices&#8221;</literal></emphasis><?linebreak?>
<xref linkend="sec_get_indices_rtas_call" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Sometimes (see
<xref linkend="dbdoclet.50569347_31867" />)</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-vpd&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_72964" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Dynamic VPD option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,manage-storage-preservation&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_28221" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Storage Preservation option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,get-dynamic-sensor-state&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_61055" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>See Requirement
<xref linkend="dbdoclet.50569332_54151" />.</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,set-dynamic-indicator&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_30542" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>See Requirement
<xref linkend="dbdoclet.50569332_58519" />.</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,change-msi&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_16274" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the MSI option. Required if any PCI Express
HB in the platform.</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,suspend-me&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_45918" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Partition Suspension option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,update-nodes&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_84414" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Update OF Tree option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,update-properties&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_40069" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Update OF Tree option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_67111" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the Configure Platform Assisted Kernel Dump
option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,query-pe-dma-window&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_99826" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry morerows="2">
<para>Required for the Dynamic DMA Window (DDW) option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,create-pe-dma-window&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_49009" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,remove-pe-dma-window&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_60545" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,reset-pe-dma-windows&#8221;</literal></emphasis><?linebreak?>
<xref linkend="dbdoclet.50569332_60545" xrefstyle="select: labelnumber" />
</para>
</entry>
<entry>
<para>Required for the LoPAR version l of the Dynamic DMA
Window (DDW) option</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold">Note:</emphasis> These commands are required in SMP platforms if
dynamic reconfiguration is required of the processors. Similarly, a
degraded mode may need these, or similar commands in the case of
detection of excessive errors. In the case of a processor deconfigured by
dynamic reconfiguration or due to excessive errors, the returned
<emphasis>CPU_status</emphasis> from the
<emphasis>query-cpu-stopped-state</emphasis> RTAS call is 2 (The processor
thread is not in the RTAS stopped state) since the deconfigured processor
cannot be started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39240"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OF properties listed in
<xref linkend="dbdoclet.50569332_38140" /> must be in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> device tree node prior to booting the
OS.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_38140">
<title>OF Device Tree Properties</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">value</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>integer size of RTAS private data area or zero if
allocation is not required</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-version&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>An integer encoding of the RTAS interface version. This
document describes version 1.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>The rate, in calls per minute, at which rtas-event-scan
should be called by the OS. See
<xref linkend="dbdoclet.50569332_24845" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-display-device&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>The
<emphasis>phandle</emphasis> of the device node used by the RTAS
call,
<emphasis>display-character</emphasis>.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;rtas-error-log-max&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>The maximum size of an extended error log.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39240"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>All RTAS functions listed as
&#8220;Required&#8221; in
<xref linkend="dbdoclet.50569332_20008" /> must be implemented in
RTAS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_39240"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis> The
functions listed as &#8220;Required in SMP Platforms&#8221; in
<xref linkend="dbdoclet.50569332_20008" /> must be implemented in
RTAS.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
<orderedlist>
<listitem>
<para>It is permitted for RTAS not to implement those optional
functions that are not appropriate or not needed on a particular
platform.</para>
</listitem>
<listitem>
<para>Vendors may introduce private RTAS calls of their own. If they
do, the property names should be of the form
<emphasis role="bold"><literal>&#8220;vendor,property&#8221;</literal></emphasis> where
<emphasis>vendor</emphasis> is a company name string as defined by OF.
Future versions of this architecture will not choose RTAS property names
that include a comma.</para>
</listitem>
</orderedlist>
<section>
<title>RTAS Device Tree Properties for Indicators and
Sensors</title>
<para>Indicators and sensors may be static or dynamic. Each indicator or
sensor type is identified by its token; a number which is associated with
the functionality of the indicator or sensor. A specific indicator token
is static in a particular platform if the number of indicators of that
type do not change with Dynamic Reconfiguration (DR) operations, and
dynamic otherwise. Certain sensors and indicators associated with DR
<footnote xml:id="pgfId-1143860">
<para>DR indicators include isolation-state (9001), DR indicator
(9002), and allocation-state (9003). DR sensors include dr-entity-sense
(9003). DR indicators and sensors are required to be there based on the
DR entity being supported. Their indices are specified by the DR index
for the DR entity. See
<xref linkend="dbdoclet.50569342_92542" /> and
<xref linkend="dbdoclet.50569342_34333" /> for more information.</para>
</footnote>are static since they represent the base hardware, others are
dynamic coming and going with extensions to the base hardware. Indices
for DR indicators and sensors are obtained from the DRC index for the DRC
connector. Information about static non-DR indicators and sensors (like
indices and location codes) are specified in the OF device tree at boot
time and do not change. Information about non-DR dynamic indicators and
sensors, needs to be gathered via the
<emphasis>ibm,get-indices</emphasis> RTAS call (see
<xref linkend="sec_get_indices_rtas_call" />), and sensors, instead of
being represented in the device tree.</para>
<para>Indicators and sensors within a platform generally have location
codes associated with them. Location code information for static
indicators and sensors, except DR indicators and sensors, are placed in
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> and
<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>
properties, respectively, in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, where &#8220;&lt;vendor&gt;&#8221; is
defined in the column marked &#8220;&lt;vendor&gt;&#8221; in
<xref linkend="dbdoclet.50569332_32237" /> and
<xref linkend="dbdoclet.50569332_23534" />, respectively. Location code
information for dynamic indicators and sensors, except DR indicators and
sensors, for the most part come in via the
<emphasis>ibm,get-indices</emphasis> call.</para>
<para>Information (index, location code) about a particular indicator or
sensor token, except DR indicators and sensors, are in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node properties or are available via the
<emphasis>ibm,get-indices</emphasis> call, but not both. When indices are
provided via the
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> properties, it is
expected that there exists a sensor/indicator for each index between 0
and
<emphasis>maxindex</emphasis>. When indices are provided via the
<emphasis>ibm,get-indices</emphasis> call, the indices may not be
contiguous, and any of the indices between 0 and
<emphasis>maxindex</emphasis> may be missing.</para>
<para>The formats for location codes are defined in
<xref linkend="dbdoclet.50569341_35066" />. For indicators and sensors,
these location codes are for the location of the device being manipulated
or measured, not the location of the specific controller or sensor. The
location code for an abstracted indicator or sensor is a NULL
string.</para>
<section xml:id="sec_indicators">
<title>Indicators</title>
<para>For static indicators, except DR indicators, OF provides for paired
integers (
<emphasis>token maxindex</emphasis>) for each indicator token under the
property
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis>
in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node. With this information, the OS can
determine which types of indicators, and the maximum number (
<emphasis>maxindex</emphasis>) of each type, that the platform
provides.</para>
<para>For static indicators, except DR indicators, the extension
property,
<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>
(see <xref linkend="dbdoclet.50569368_41461" />), provides an array of strings
containing the FRU location codes associated with each indicator. See
<xref linkend="dbdoclet.50569341_35066" />. Here, &#8220;
<emphasis>&lt;vendor&gt;</emphasis>&#8221; corresponds to the
&#8220;&lt;vendor&gt;&#8221; column of
<emphasis>
<xref linkend="dbdoclet.50569332_32237" />
</emphasis> and &#8220;
<emphasis>&lt;token&gt;</emphasis>&#8221; corresponds to the token of the
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis>
type.
The index of a specific indicator token is used to index into the array
up to
<emphasis>maxindex</emphasis>.</para>
<para>Indices and location codes for dynamic indicators are obtained via
the
<emphasis>ibm,get-indices</emphasis> RTAS call and do not appear in the
static properties in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
<para>Indices for DR indicators 9001, 9002, and 9003 are obtained from
the DRC index for the DRC connector. See Requirement
<xref linkend="dbdoclet.50569342_16260" />.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_74895">
<term><emphasis role="bold">R1-<xref linkend="sec_indicators"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For all static
indicators, except DR indicators 9001, 9002, and 9003, OF must provide
the extension property,
<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>,
in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, unless the indicator is part of an
extension which has its own set of appropriate properties for the
indicator, where &#8220;
<emphasis>&lt;vendor&gt;</emphasis>&#8221; must be as defined in the
column labeled &#8220;&lt;vendor&gt;&#8221; in
<xref linkend="dbdoclet.50569332_32237" /> for the specific indicator
token value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_indicators"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>For all static indicators for which
there is an associated
<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 and for which there is not a
physical realization, the location code string must be NULL.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_indicators"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Indices and location codes for any
indicator token, except DR indicators 9001, 9002, and 9003, for which the
number of such indicators in the platform may change dynamically, must be
obtained via the
<emphasis>ibm,get-indices</emphasis> RTAS call and the indicator token
must not appear in 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>
or <emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_indicators"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The indicator token of 4 must not exist
in a platform when a Error Log (token 9006) is implemented.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_sensors">
<title>Sensors</title>
<para>For static sensors, except DR sensors, OF currently provides for
paired integers (
<emphasis>token maxindex</emphasis>) for each sensor token under the
property
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis>
in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node. With this information, the OS can
determine which types of sensors, and how many of each type, that the
platform provides.</para>
<para>For static sensors, except DR sensors, the extension property,
<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>
(see <xref linkend="dbdoclet.50569368_41461" />), provides an array of strings
containing the FRU location codes associated with each sensor. See
<xref linkend="dbdoclet.50569341_35066" />. Here, &#8220;
<emphasis>&lt;vendor&gt;</emphasis>&#8221; corresponds to the
&#8220;&lt;vendor&gt;&#8221; column of
<emphasis>
<xref linkend="dbdoclet.50569332_23534" />
</emphasis> and &#8220;
<emphasis>&lt;token&gt;</emphasis>&#8221; corresponds to the token in the
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property. The index of a
specific sensor is used to index into the array up to
<emphasis>maxindex</emphasis>.</para>
<para>Indices and location codes for dynamic sensors, except DR sensors,
are obtained via the
<emphasis>ibm,get-indices</emphasis> RTAS call and do not appear in the
static properties in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
<para>Indices for DR sensors 9003 are obtained from the DRC index for the
DRC connector. See Requirement
<xref linkend="dbdoclet.50569342_43470" />.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_29762">
<term><emphasis role="bold">R1-<xref linkend="sec_sensors"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For all static
sensors, except DR sensor 9003, OF must provide the extension property,
<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>, in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, unless the sensor is part of an extension
which has its own set of appropriate properties for the sensor, where
&#8220;
<emphasis>&lt;vendor&gt;</emphasis>&#8221; must be as defined in the
column labeled &#8220;&lt;vendor&gt;&#8221; in
<xref linkend="dbdoclet.50569332_23534" /> for the specific sensor token
value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sensors"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>For all static sensors for which there
is an associated
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
property and for which there is not a
physical realization, the location code string must be NULL.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sensors"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Indices and location codes for any
sensor token, except DR sensor 9003, for which the number of such sensors
in the platform may change dynamically, must be obtained via the
<emphasis>ibm,get-indices</emphasis> RTAS call and the sensor token must
not appear in the
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
or <emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sensors"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The following sensor tokens must not be
implemented if the number of them may be changed by a DR operation (that
is, they can only be used when static): 3, 9001, and 9002.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="sec_calling_mech_convent">
<title>Calling Mechanism and Conventions</title>
<para>
RTAS is
called through a mechanism similar to the OF client interface service. An
argument buffer is constructed which describes the desired RTAS call.
This description includes an indication of the RTAS call that is being
invoked, the number and value of the input parameters, the number of
result values, and space for each of the result values.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>In order to make an RTAS call, the OS must
construct an argument call buffer aligned on an eight byte boundary in
physically contiguous real memory as described by
<xref linkend="dbdoclet.50569332_22280" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_22280">
<title>RTAS Argument Call Buffer</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Cell Number</emphasis>
</para>
</entry>
<entry align="center" >
<para>
<emphasis role="bold">Use</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Token Specifying which RTAS Call</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Number of Input Parameters</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>Number of Output Parameters</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>First Input Parameter</para>
</entry>
</row>
<row>
<entry>
<para>...</para>
</entry>
<entry>
<para></para>
<para>Other Input Parameters</para>
</entry>
</row>
<row>
<entry>
<para>4 + Number of Inputs -1</para>
</entry>
<entry>
<para>Last Input Parameter</para>
</entry>
</row>
<row>
<entry>
<para>4 + Number of Inputs</para>
</entry>
<entry>
<para>First Output Parameter</para>
</entry>
</row>
<row>
<entry>
<para>...</para>
</entry>
<entry>
<para></para>
<para>Other Output Parameters</para>
</entry>
</row>
<row>
<entry>
<para>4 + Number of Inputs</para>
<para>+ Number of Outputs -1</para>
</entry>
<entry>
<para>Last Output Parameter</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_29738">
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>If the system is
a 32-bit system, or if RTAS was instantiated by
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis>, then all
cells in
the RTAS argument buffer must be 32-bit sign extended values that are
aligned to 4 byte boundaries.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_38752">
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>If the system is
a 64 bit system and if RTAS was instantiated by
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis>, then all
cells in the RTAS argument buffer must be 64-bit sign extended values
that are aligned to 8 byte boundaries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>RTAS functions must be invoked by branching
to the
<emphasis>rtas-call</emphasis> address which is returned by the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis>
or
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis>
OF method (see
<xref linkend="dbdoclet.50569332_14005" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Register R3 must contain the argument
buffer&#8217;s real address when
<emphasis>rtas-call</emphasis> is invoked.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Register R4 must contain the real address
of the RTAS private data area when
<emphasis>rtas-call</emphasis> is invoked (see Requirement
<xref linkend="dbdoclet.50569332_37664" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_calling_mech_convent"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The Link Register must contain the return
address when
<emphasis>rtas-call</emphasis> is invoked.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Notes:</emphasis> </para>
<orderedlist>
<listitem>
<para>RTAS is not required to perform sanity checking of its input
parameters. Using invalid values for any parameter in an RTAS argument
buffer gives undefined results. However, when such checks are made, the
appropriate return code for invalid parameters is -3.</para>
</listitem>
<listitem>
<para>The token that specifies the RTAS call is obtained by looking up
the desired call from the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node of the OF device tree.</para>
</listitem>
<listitem>
<para>The OS must be aware that the effective address range for RTAS
is 4 GB when instantiated in 32-bit mode and the OS should not pass RTAS
addresses or blocks of data which might fall outside of this
range.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="dbdoclet.50569332_16759">
<title>Return Codes</title>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_94431">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16759"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The first output
value of all the RTAS functions must be a
<emphasis>Status</emphasis> word which denotes the result of the call. The
<emphasis>Status</emphasis> word takes on one of the values in
<xref linkend="dbdoclet.50569332_10584" />. Non-negative values indicate
success.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_10584">
<title>RTAS
<emphasis>Status</emphasis> Word Values</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">
<emphasis>Status</emphasis> Word Meanings</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>RTAS function call succeeded.</para>
</entry>
</row>
<row>
<entry>
<para>-1</para>
</entry>
<entry>
<para>RTAS function call encountered a hardware error.</para>
</entry>
</row>
<row>
<entry>
<para>-2</para>
</entry>
<entry>
<para>A necessary hardware device was busy, and the requested
function could not be performed. The operation should be
retried at a later time.</para>
</entry>
</row>
<row>
<entry>
<para>-3</para>
</entry>
<entry>
<para>Parameter Error.</para>
<para>In some cases, specific parameter errors are enumerated.
However, other parameter errors may be reported using this
return code in addition to those enumerated.</para>
</entry>
</row>
<row>
<entry>
<para>-7</para>
</entry>
<entry>
<para>Unexpected state change.</para>
</entry>
</row>
<row>
<entry>
<para>9000-9899</para>
</entry>
<entry>
<para>Reserved for vendor specific success codes.</para>
</entry>
</row>
<row>
<entry>
<para>990x</para>
</entry>
<entry>
<para>Extended delay - where x is a number in the range of
0-5</para>
</entry>
</row>
<row>
<entry>
<para>-9000</para>
</entry>
<entry>
<para>Multi-level isolation error (see
<xref linkend="dbdoclet.50569342_11827" />).</para>
</entry>
</row>
<row>
<entry>
<para>-9004 - (-9999)</para>
</entry>
<entry>
<para>Reserved for vendor specific error codes.</para>
</entry>
</row>
<row>
<entry>
<para>Additional Negative Numbers</para>
</entry>
<entry>
<para>An error was encountered. The meaning of this error is
specific to the RTAS function that was invoked.</para>
</entry>
</row>
<row>
<entry>
<para>Additional Positive Numbers</para>
</entry>
<entry>
<para>The function succeeded. The meaning of the
<emphasis>Status</emphasis> word is specific to the RTAS
function that was invoked.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
<para>
<xref linkend="dbdoclet.50569332_10584" /> indicates a summation of all
possible
<emphasis>Status</emphasis> word values. A given RTAS function cannot
yield all of the possible
<emphasis>Status</emphasis> words. For the specific
<emphasis>Status</emphasis> words which apply to a specific RTAS function,
see the semantics for that function.</para>
<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>
<orderedlist>
<listitem>
<para>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>
</listitem>
<listitem>
<para>When the extended delay (990x) is returned, it is suggested that
software delay for 10 raised to the x milliseconds, where x is the last
digit of the 990x return code, before calling the function again.</para>
</listitem>
</orderedlist>
</section>
</section>
Reference in New Issue View Git Blame Copy Permalink