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 'aa7593c479'
${ noResults }
Linux-Architecture-Reference/RTAS/sec_rtas_get_indices.xml

6036 lines
263 KiB
XML
Raw Normal View History Unescape Escape

Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="sec_get_indices_rtas_call">
<title><emphasis>ibm,get-indices</emphasis> Call</title>
<para>The RTAS function
<emphasis>ibm,get-indices</emphasis> is used to obtain the indices and
location codes for a specified indicator or sensor token. It allows for
obtaining the list of indicators and sensors dynamically and therefore
assists in any Dynamic Reconfiguration operation that involves indicators
and sensors being added or deleted from the platform (unlike the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
and <emphasis role="bold"><literal>&#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).
This call also allows discontiguous indices for a particular indicator or
sensor type (unlike the
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>
&#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).</para>
<para>This RTAS call is not used for DR indicators (9001, 9002, and 9003)
or DR sensors (9003). See the following sections in the DR chapter for more
information:
<xref linkend="LoPAR.Virtualization" /> and
<xref linkend="LoPAR.Virtualization" />.</para>
<para>It may require several calls to the
<emphasis>ibm,get-indices</emphasis> RTAS routine to get the entire list of
indicators or sensors of a particular type. Each call may specify a
different work area.</para>
<para>The OS may not interleave calls to
<emphasis>ibm,get-indices</emphasis> for different indicator or sensor
types. Other standard RTAS locking rules apply.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The RTAS function
<emphasis>ibm,get-indices</emphasis> must implement the argument call buffer
defined by
<xref linkend="dbdoclet.50569332_50675" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_50675">
<title>Argument Call Buffer
<emphasis>ibm,get-indices</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="7">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-indices</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator or Sensor</emphasis>
</para>
</entry>
<entry>
<para>0: indicator of given type</para>
<para>1: sensor of given type</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator Type</emphasis>
</para>
</entry>
<entry>
<para>Indicator or sensor type (for example, 9006, 9007)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>Address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Starting Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing first indicator number to
return</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-3: Indicator type not supported</para>
<para>-4: Optional: Indicator list changed, start again</para>
<para>0: Success</para>
<para>1: More data available; call again</para>
<para>990x:Extended Delay where x is a number 0-5 (see text
below)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Starting Number</emphasis>
</para>
</entry>
<entry>
<para>Integer to use as the Starting Number parameter on the next
call, or 1 if no more calls are required</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When the 990x
<emphasis>Status</emphasis> is returned, it is suggested that software delay
for 10 raised to the x milliseconds (where x is the last digit of the 990x
return code), before calling
<emphasis>ibm,get-indices</emphasis> with the same Starting Number and
Indicator Type. However, software may issue the
<emphasis>ibm,get-indices</emphasis> call again either earlier or later than
this.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The OS must not interleave calls to
<emphasis>ibm,get-indices</emphasis> for different indicator or sensor
types.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>On the first call to get a particular
<emphasis>Indicator Type</emphasis>, the caller must provide a Starting
Number of 1 (32-bit integer)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>When
<emphasis>ibm,get-indices</emphasis> is called with a Starting Number of 1,
firmware must refresh any stale data in previously cached firmware buffers
for that indicator (for example, data made stale by a Dynamic
Reconfiguration operation).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>When calling
<emphasis>ibm,get-indices</emphasis> with a Starting Number of 1, a
previously returned
<emphasis>Next Starting Number</emphasis> value must be discarded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Optionally, if firmware detects a change in
the indicator list before the entire list is returned, the
<emphasis>ibm,get-indices</emphasis> call must return a -4 and the caller
must start again with a Starting Number of 1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The return data format in the work area for
all sensors and indicators must be as follows:</para>
<itemizedlist>
<listitem>
<para>Number Returned: 32-bit integer representing the number of
indicator indices returned on this call</para>
</listitem>
<listitem>
<para>Sets of (32-bit integer index, 32-bit integer length of location
code including NULLs, location code string (NULL terminated and padded to
nearest 4 byte boundary)), one set per indicator or sensor, with the number
of sets indicated by the first integer in this work buffer</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>If the
<emphasis>Status</emphasis> returned is 1 (more data available, call again),
then the caller must call
<emphasis>ibm,get-indices</emphasis> again with the
<emphasis>Starting Number</emphasis> parameter set to the Next Starting
Number integer from the previously returned buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must return the
<emphasis>Status</emphasis> value of -3 for the following conditions:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Indicator type not supported</para>
</listitem>
<listitem>
<para>No indicators of specified Indicator Type available to
caller</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>If the <emphasis>ibm,get-indices</emphasis> RTAS call returns a
<emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
caller must consider that the contents of the work area is not
defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>The work area specified in the
<emphasis>ibm,get-indices</emphasis> RTAS call argument buffer must be
contiguous in logical real memory and must reside below 4GB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must only return the
indicator or sensor indices to which the caller has authorized access at
the time of the call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must make no assumptions
about the contents of the work area on the beginning of the call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>When the platform supports the
<emphasis>ibm,get-indices</emphasis> RTAS call, the device tree must include
the
<emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property
in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting
indicator information and must include the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property in
the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting sensor
information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>When an indicator token is provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property,
it must not be included in the
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
property and must not be included in the
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para>When a sensor token is provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property, it
must not be included in the
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
property and must not be included in the
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para>When an environmental sensor token is
provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property,
users of data in the
<emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis> property for
that sensor token must not assume that the indices are contiguous for that
sensor token (that is, any of the indices between 0 and the maxindex,
inclusive, may be missing).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_80480">
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para>When the value of
any index returned is 0xFFFFFFFF, the OS must use the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> and
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS functions for this
sensor or indicator, using the location code to identify the sensor or
indicator.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>get-sensor-state</emphasis> or
<emphasis>get-indicator</emphasis> with an index value of 0xFFFFFFFF.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569332_30542">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call behaves as the RTAS
<emphasis>set-indicator</emphasis> call, except that the instance of the
indicator is identified by a location code instead of a index.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_58519">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms that
implement any indicators that are identified by location code instead of
index (see Requirement
<xref linkend="dbdoclet.50569332_80480" />) must implement the
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,set-dynamic-indicator</emphasis> must implement the argument
call buffer defined by
<xref linkend="dbdoclet.50569332_14870" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14870">
<title>Argument Call Buffer
<emphasis>ibm,set-dynamic-indicator</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">
<emphasis>Name</emphasis>
</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="5">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,set-dynamic-indicator</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator</emphasis>
</para>
</entry>
<entry>
<para>Token defining the indicator</para>
<para>9006: Error Log</para>
<para>9007: Identify Indicator</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>State</emphasis>
</para>
</entry>
<entry>
<para>Desired new state; see
<xref linkend="dbdoclet.50569332_32237" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Location Code Address</emphasis>
</para>
</entry>
<entry>
<para>Real or Logical address of a location code string, in the
format defined by Requirement
<xref linkend="dbdoclet.50569332_69341" /></para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy, try again later</para>
<para>-3: No such indicator</para>
<para>0: Success</para>
<para>990x: Extended delay, where x is a number between 0 and
5, as described below</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the power
<emphasis>x</emphasis> milliseconds (where
<emphasis>x</emphasis> is the last digit of the 990x return code), before
calling
<emphasis>ibm,set-dynamic-indicator</emphasis> with the same indicator
type and location code. However, software may call
<emphasis>ibm,set-dynamic-indicator</emphasis> again either earlier or
later than this.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>ibm,set-dynamic-indicator</emphasis> with a different indicator
until a non-busy return
<emphasis>Status</emphasis> has been received from the previous
<emphasis>ibm,set-dynamic-indicator</emphasis> call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The location code string referenced by the
<emphasis>Location Code Address</emphasis> argument in the
<emphasis>ibm,set-dynamic-indicator</emphasis> argument call buffer must
reside in contiguous in real memory below an address of 4GB.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_69341">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>The input data
format in the work area must be as follows:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>32-bit integer length of the location code string, including
NULL</para>
</listitem>
<listitem>
<para>Location code string, NULL terminated, identifying the sensor to
be set.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The platform must not modify the location
code string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The OS must only use this call for
indicators which have been provided by the
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
0xFFFFFFFF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>Platforms must identify all indicators
except types 9006 and 9007 by index.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS call must return A
<emphasis>Status</emphasis> of -3 for the following conditions:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Indicator type not supported</para>
</listitem>
<listitem>
<para>The specified location code does not identify a valid
indicator</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_61055">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call behaves as the RTAS
<emphasis>get-sensor-state</emphasis> call, except that the instance of
the sensor is identified by a location code instead of a index.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569332_54151">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms that
implement any sensors that are identified by location code instead of
index (see Requirement
<xref linkend="dbdoclet.50569332_80480" />) must implement the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,get-dynamic-sensor-state</emphasis> must implement the
argument call buffer defined by
<xref linkend="dbdoclet.50569332_71500" />.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71500">
<title>Argument Call Buffer
<emphasis>ibm,get-dynamic-sensor-state</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-dynamic-sensor-state</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Sensor</emphasis>
</para>
</entry>
<entry>
<para>Token defining the sensor</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Location Code Address</emphasis>
</para>
</entry>
<entry>
<para>Real or Logical address of a location code string, in the
format defined by Requirement
<xref linkend="dbdoclet.50569332_75857" /></para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy, try again later</para>
<para>-3: No such indicator</para>
<para>0: Success</para>
<para>990x: Extended delay, where x is a number between 0 and
5, as described below</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>State</emphasis>
</para>
</entry>
<entry>
<para>Current state of the sensor as defined in the
<emphasis>Defined Values</emphasis> column of
<xref linkend="dbdoclet.50569332_23534" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the power
<emphasis>x</emphasis> milliseconds (where
<emphasis>x</emphasis> is the last digit of the 990x return code), before
calling
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with the same indicator
type and location code. However, software may call
<emphasis>ibm,get-dynamic-sensor-state</emphasis> again either earlier or
later than this.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with a different sensor
until a non-busy return
<emphasis>Status</emphasis> has been received from the previous
<emphasis>ibm,get-dynamic-sensor-state</emphasis> call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The work area must be contiguous in real
memory and must reside below 4GB.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_75857">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>The input data
format in the work area must be as follows:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>32-bit integer length of the location code string, including
NULL</para>
</listitem>
<listitem>
<para>Location code string, NULL terminated, identifying the sensor to
be set.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The platform must not modify the location
code string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The OS must only use this call with sensors
which have been provided by the
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
0xFFFFFFFF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>The platform must use the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS call only for
dynamic sensor types of 9004, 9006 and 9007.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>A <emphasis>Status</emphasis> of -3 must be returned for the following
conditions:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Sensor type not supported</para>
</listitem>
<listitem>
<para>The specified location code does not identify a valid
sensor</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_72964">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,get-vpd</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call allows for collection of VPD that changes after OS
boot time (after the initial reporting in the OF device tree). When this
call is implemented, there is no overlap between what is reported in the
device tree and what is reported with this RTAS call. Also, when this
RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
is dynamically changed during OS run time is reported with this call and
not via the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property in the OF device
tree.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For all Dynamic Reconfiguration options
except PCI Hot Plug, when the platform VPD can change dynamically due to
a Dynamic Reconfiguration operation, the platform must implement the
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,get-vpd</emphasis> must implement the argument call buffer
defined by
<xref linkend="dbdoclet.50569332_62393" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62393">
<title>Argument Call Buffer
<emphasis>ibm,get-vpd</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="6">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-vpd</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Pointer to Location Code</emphasis>
</para>
</entry>
<entry>
<para>Real address of NULL-terminated string, contiguous in
real memory and below 4GB, which is the location code of the
FRU for which to obtain the VPD. When this parameter references
a NULL string the VPD for all location codes is
returned.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>Address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the sequence number of the call.
First call in sequence starts with 1, following calls (if
necessary) use the
<emphasis>Next Sequence Number</emphasis> returned from the
previous call.</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-3: Parameter error</para>
<para>-4: Optional: VPD changed, start again</para>
<para>0: Success</para>
<para>1: More data available; call again</para>
<para>990x: Extended Delay where x is a number 0-5 (see text
below)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Return this integer as the
<emphasis>Sequence Number</emphasis> parameter on the next call
to continue the sequence, or 1 if no more calls are
required</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Bytes Returned</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the number of valid bytes returned
in the work area.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When the 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
the 990x return code), before calling
<emphasis>ibm,get-vpd</emphasis> with the same input parameters. However,
software may issue the
<emphasis>ibm,get-vpd</emphasis> call again either earlier or later than
this.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>On the first call to
<emphasis>ibm,get-vpd</emphasis> for a particular VPD gathering operation,
the caller must provide a
<emphasis>Sequence Number</emphasis> of 1 (32-bit integer)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Upon calling
<emphasis>ibm,get-vpd</emphasis> with a
<emphasis>Sequence Number</emphasis> of 1, a previously returned
<emphasis>Next Sequence Number</emphasis> must be discarded. This means
that multiple calls to
<emphasis>ibm,get-vpd</emphasis> cannot be interleaved by multiple
processors, and if processor &#8220;B&#8221; starts a new
<emphasis>ibm,get-vpd</emphasis> sequence while processor &#8220;A&#8221;
has a call sequence in process (that is, the function on processor
&#8220;A&#8221; has returned a
<emphasis>Status</emphasis> of 1, and the subsequent call has not yet been
made) then the call sequence on processor &#8220;A&#8221; is
abandoned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Optionally, if firmware detects a change in
the VPD being requested before the entire VPD is returned, the
<emphasis>ibm,get-vpd</emphasis> call must return a
<emphasis>Status</emphasis> of -4 and the caller must start again with a
Starting Number of 1.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> The platform should not impede
forward progress by continuously returning a
<emphasis>Status</emphasis> of -4.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The return data format in the work area
must be such that after returning all the data and concatenating all data
together in the order received, that the data is the same as is obtained
from the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property of the OF device
tree.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>Each stanza of the returned data must
include the YL (location code) keyword.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then the
platform must not provide the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> properties in the OF
device tree
<emphasis>root</emphasis> node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then any VPD
which may change after OS boot must be reported via the
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>If the
<emphasis>Status</emphasis> returned is 1 (more data available, call
again), then the caller must call
<emphasis>ibm,get-vpd</emphasis> again with the
<emphasis>Sequence Number</emphasis> parameter set to the
<emphasis>Next Sequence Number</emphasis> integer from the previously
returned call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>If a
<emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
contents of the work area is not defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The work area must be contiguous in real
memory and must reside below 4GB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>Firmware cannot count on the contents of
the work area at the beginning of any call to
<emphasis>ibm,get-vpd</emphasis> (regardless of the value of the
<emphasis>Sequence Number</emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>The location code referenced by the
<emphasis>Pointer to Location Code</emphasis> parameter must reside in
contiguous real memory below an address of 4GB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then firmware
must supply the
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, the value of which is a single cell,
encoded as with
<emphasis>encode-int</emphasis>, which is the estimated maximum size in
bytes of the VPD that is returned if the
<emphasis>Pointer to Location Code</emphasis> parameter to the
<emphasis>ibm,get-vpd</emphasis> RTAS function is NULL (that is, all
system VPD). This size should take in to account possible concurrent
addition of new platform elements after the partition is started. If
firmware is unable to estimate this size, it may return a value of 0x0 to
indicate that no estimate is available.</para>
<para>
<emphasis role="bold">Software Implementation Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>An OS should be prepared for older versions of firmware where
the
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property is not
provided.</para>
</listitem>
<listitem>
<para>Each stanza of the returned data must include the YL (location
code) keyword.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_28221">
<title>Managing Storage Preservation</title>
<para>Platforms may optionally preserve selected regions of storage
(LMBs) across client program boot cycles.
<xref linkend="LoPAR.Platform" /> for more information.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must implement the
<emphasis>ibm,manage-storage-preservation</emphasis> RTAS argument call
buffer as defined by
<xref linkend="dbdoclet.50569332_95221" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_95221">
<title><emphasis>ibm,manage-storage-preservation</emphasis> Argument Call
Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="5">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,manage-storage-preservation</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Subfunction</emphasis>
</para>
</entry>
<entry>
<para>0 = unused (return -3)</para>
<para>1 = Register specified LMB for preservation</para>
<para>2 = Query preservation state of specified LMB</para>
<para>3 = Deregister for preservation Specific LMB</para>
<para>4 = Deregister for preservation all caller&#8217;s
LMBs.</para>
<para>All other values reserved (return -3)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Reg High</emphasis>
</para>
</entry>
<entry>
<para>The high order 32 bits of the LMB's
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
1-3)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Reg Low</emphasis>
</para>
</entry>
<entry>
<para>The low order 32 bits of the LMB's
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
1-3)</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy</para>
<para>-3: Parameter error (Subfunction or Reg invalid; or Reg
for a non-preservable LMB)</para>
<para>0: Success</para>
<para>990x: Extended delay where x is a number 0-5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Preservation state</emphasis>
</para>
</entry>
<entry>
<para>If
<emphasis>Status</emphasis>= Success, the current preservation
state of specified LMB (Subfunctions 1-3)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must include the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property in the
<emphasis>/memory</emphasis> nodes of its OF device tree, containing a
value which reflects the platform's ability to preserve the specific
LMB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The value of the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
LMB must be 0 (cannot be preserved).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must not preserve the first LMB, thus must indicate a value of 0 for the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
LMB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must include the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property in the
<emphasis>/memory</emphasis> nodes of its OF device tree, valued to
reflect the platform's preservation state of the specific LMB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
a reboot, must include in the OF
<emphasis role="bold"><literal>/rtas</literal></emphasis> node the
<emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis> property if the
previous client program registered one or more of its LMBs for
preservation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> If the client
program registered an LMB for preservation, the platform must preserve
the LMB's storage state across client program reboots.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
a reboot, must include in the OF
<emphasis role="bold"><literal>/rtas</literal></emphasis> node the
<emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis> property
which reflects the value of the partition shutdown configuration
variable, and if this property is not present, a value of 0 must be
assumed by the OS.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_26596">
<title><emphasis>ibm,lpar-perftools</emphasis> RTAS Call</title>
<para>This RTAS call provides access to platform-level facilities for
performance tools running in a partition on an LPAR system. Platforms may
require platform-specific tools, beyond the scope of this architecture,
to make this call available.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> The platform
must implement the LPAR option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> RTAS must
implement the
<emphasis>ibm,lpar-perftools</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_48993" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_48993">
<title>Argument Call Buffer
<emphasis>ibm,lpar-perftools</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="7">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,lpar-perftools</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Subfunction</emphasis>
</para>
</entry>
<entry>
<para>1: Convert hypervisor IAR value to method name.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address High</emphasis>
</para>
</entry>
<entry>
<para>Most significant 32 bits of real address of work
area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address Low</emphasis>
</para>
</entry>
<entry>
<para>Least significant 32 bits of real address of work
area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area in bytes</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the sequence number of this call.
First call in sequence starts with 1, following calls (if
necessary) use the
<emphasis>Next Sequence Number</emphasis> returned from the
previous call.</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error (Subfunction invalid, invalid work
area address, invalid work area size)</para>
<para>-9002: Partition does not have authority to perform this
function</para>
<para>-5: Buffer was too small to supply requested data</para>
<para>0: Success</para>
<para>990x: Extended delay</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Return this integer as the
<emphasis>Sequence Number</emphasis> parameter on the next call,
or 1 if no more calls are required.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
the 990x return code), before calling the
<emphasis>ibm,lpar-perftools</emphasis> call with the same input
parameters. However, software may issue the
<emphasis>ibm,lpar-perftools</emphasis> call again earlier or later than
this.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> For
<emphasis>subfunction</emphasis> value 1, on input the first 8 bytes of
the work area must contain the hypervisor IAR address to be converted. On
output, the first 8 bytes of the work area contain the offset of this
address from the start of the hypervisor function, method or module,
followed by a NULL-terminated text string containing the name of the
hypervisor function, method or module. If the address is not a valid
address in the hypervisor, on output the buffer must contain 0x0 (8
bytes) followed by a NULL-terminated text string indicating that the
address was not valid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool support option:</emphasis> The work
area must reside in contiguous memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> If a
<emphasis>Status</emphasis> of anything other than 0 is returned, the
contents of the work area are not defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> A partition
must have at most one call to this function in process at a given time.
This means that if one processor in the partition initiates this call,
receives a Busy or Extended Delay return, and then another processor
calls this function with a sequence number of 1, a subsequent call using
the
<emphasis>Next Sequence Number</emphasis> returned to the first processor
results in a Parameter Error return code.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_45918">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,suspend-me</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>The
<emphasis>ibm,suspend-me</emphasis> RTAS call provides the calling OS the
ability to suspend processing. Suspension of processing is required as
part of OS hibernation or migration to another platform. This RTAS call
is made by the last active processor thread of a partition. The OS uses
the H_JOIN hcall() (see
<xref linkend="LoPAR.Virtualization" />) to deactivate other
processing threads. Processing treads may exit H_JOIN due to an
unmaskable interrupt; if a thread has exited H_JOIN,
<emphasis>ibm,suspend-me</emphasis> fails with a status of &#8220;multiple
processor threads active&#8221;. The wake up from suspension is triggered
by partition state change (see
<xref linkend="LoPAR.Virtualization" /> sections on "Partition Migration"
and "Partition Hibernation"). The
<emphasis>ibm,suspend-me</emphasis> RTAS call returns only on the calling
virtual processor. Other virtual processors that were inactive when
<emphasis>ibm,suspend-me</emphasis> was called remain so until they are
proded by the OS.</para>
<para>While the logical configuration of a suspended partition remains
static, the physical properties may change; the OS may wish to issue
<emphasis>ibm,update-nodes</emphasis> (see
<emphasis>
<xref linkend="dbdoclet.50569332_84414" />) to determine if any device
tree nodes changed, and then</emphasis> refresh its view of the device
tree physical properties using
<emphasis>ibm,update-properties</emphasis> (see
<xref linkend="dbdoclet.50569332_40069" />) and/or
<emphasis>ibm,configure-connector</emphasis> (see
<xref linkend="LoPAR.Virtualization" />). Also during suspension, some
system parameters may have changed. See
<xref linkend="dbdoclet.50569332_10519" />, for details. The OS may want
to re-scan selected system parameters.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the Logical Partitioning option (see
<xref linkend="LoPAR.Virtualization" />)
<emphasis>.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> RTAS must
implement the
<emphasis>ibm,suspend-me</emphasis> call within a logical partition using
the argument call buffer defined by
<xref linkend="dbdoclet.50569332_91600" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_91600">
<title>Argument Call Buffer
<emphasis>ibm,suspend-me</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="2">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,suspend-me</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>9000: Suspension Aborted</para>
<para>0: Success -- expected return on function resume</para>
<para>-1: Hardware Error</para>
<para>&#160;</para>
<para>-9004: Partition not suspendable</para>
<para>-9005: Multiple processor threads active</para>
<para>-9006: Outstanding COP Operations</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition is in the &#8220;suspendable state&#8221;, else return
a status of -9004 &#8220;Partition not suspendable&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition has no other active processor thread, else return a
status of -9005 &#8220;Multiple processor threads active&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the Thread Join option (see
<xref linkend="LoPAR.Virtualization" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must restore all partition state as of the time of the call to
<emphasis>ibm,suspend-me</emphasis> prior to returning from the
<emphasis>ibm,suspend-me</emphasis> RTAS call, except for the values of
those Open Firmware Device tree properties as reported using the Update
OF Tree option, and the system parameters given in
<xref linkend="dbdoclet.50569332_10519" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must be prepared to respond to OS requests for updated device tree
information immediately after returning from the
<emphasis>ibm,suspend-me</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must support the &#8220;update OF tree&#8221; option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must support the &#8220;Partner partition suspended&#8221; CRQ Transport
Event (See
<xref linkend="LoPAR.Virtualization" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
deliver &#8220;Partner partition suspended&#8221; CRQ Transport Events to
both CRQs of all CRQ connections associated with the partition calling
<emphasis>ibm,suspend-me.</emphasis></para>
<para><emphasis role="bold">Note:</emphasis> The transport events are visible to the partition calling
<emphasis>ibm,suspend-me</emphasis> after the subsequent resume from
suspension, while the transport events are immediately visible to the
partner partitions of the caller at the time of the suspend.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
set the state of all of the caller&#8217;s CRQs to disabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the H_ENABLE_CRQ hcall() using the syntax and semantics
described in
<xref linkend="LoPAR.Virtualization" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For platforms that implement the Partition Suspension and VSCSI
options:</emphasis> The
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property of the
platform&#8217;s
<emphasis>v-scsi</emphasis> and
<emphasis>v-scsi-host</emphasis> nodes must include
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-2&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-host-2&#8221;</literal></emphasis> respectively
indicating the platform supports the &#8220;Partner partition
suspended&#8221; CRQ Transport Event.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> If the OS is
participating in OS surveillance, to avoid a surveillance time out, the
OS must disable surveillance (see
<xref linkend="dbdoclet.50569332_60143" />) prior to calling
<emphasis>ibm,suspend-me</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the LRDR option (See
<xref linkend="LoPAR.Virtualization" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The logical
configuration of a partition, including its view of the
<emphasis>rtas-display-device</emphasis>, and rtas tone facility must not
change while a partition is suspended.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must not change the support for a system parameter during
suspension.</para>
<para>
<emphasis role="bold">NOTE:</emphasis> If RTAS returns a status of -3 (System
parameter not supported) prior to suspension, it returns a Status of -3
for accesses to that same system parameter after suspension. Similarly if
RTAS does not return a Status of -3 prior to suspension for a given
system parameter, it does not do so after suspension.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must limit the system parameters that change values during suspension to
those specified in
<xref linkend="dbdoclet.50569332_10519" /> (all system parameters not
specified are preserved).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must preserve up to the first 32 SLB entries for each partition processor
during the suspension. Other SLB entries are subject to loss.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option with the Platform
Facilities Option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition has no outstanding coprocessor operations else return a
status of -9005 &#8220;Outstanding COP Operations&#8221;.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_10519">
<title>System Parameters that May Change During Partition
Migration and Hibernation</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">System Parameter Token</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">&#160;</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0-15</para>
</entry>
<entry>
<para>HMC</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>18-19</para>
</entry>
<entry>
<para>Legacy processor CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>20</para>
<para>&#160;</para>
</entry>
<entry>
<para>SPLPAR characteristics</para>
</entry>
<entry>
<para>Only specified SPLPAR keywords may change value</para>
</entry>
</row>
<row>
<entry morerows="6">
<para>&#160;</para>
</entry>
<entry>
<para>DesiredEntitledCapacity</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredMemory</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredNumberOfProcessors</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredVariableCapacityWeight</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DispatchWheelRotationPeriod</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>MinimumEntitledCapacityPerVP</para>
</entry>
<entry>
<para>Platform prevents migration where current Entitled
Capacity/VCPU ratio would be below the target's minimum.</para>
</entry>
</row>
<row>
<entry>
<para>MaximumPlatformProcessors</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>22</para>
</entry>
<entry>
<para>platform_auto_power_restart</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>23</para>
</entry>
<entry>
<para>sp-remote-pon</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>24</para>
</entry>
<entry>
<para>sp-rb4-pon</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>25</para>
</entry>
<entry>
<para>sp-snoop-str</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>30</para>
</entry>
<entry>
<para>sp-call-home</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>31</para>
</entry>
<entry>
<para>sp-current-flash-image</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>33</para>
</entry>
<entry>
<para>epow3-quiesce-time</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>34</para>
</entry>
<entry>
<para>memory-preservation-boot-time</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>35</para>
</entry>
<entry>
<para>SCSI initiator identifier</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>36</para>
</entry>
<entry>
<para>AIX support</para>
</entry>
<entry>
<para>The keyword &#8220;support&#8221; may not change to the
value &#8220;no&#8221; for an AIX client.</para>
</entry>
</row>
<row>
<entry>
<para>37</para>
</entry>
<entry>
<para>enhanced processor CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>38</para>
</entry>
<entry>
<para>enhanced memory CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>39</para>
</entry>
<entry>
<para>CoD Options</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>41</para>
</entry>
<entry>
<para>firmware boot options</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>43</para>
</entry>
<entry>
<para>processor module information</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_84414">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,update-nodes</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call is used to determine which device tree nodes have
changed due to a massive platform reconfiguration such as when the
partition is migrated between machines. Differing platform
reconfigurations are expected to potentially result in different sets of
nodes being updated; the &#8220;scope&#8221; argument communicates what
set of changes are to be reported. The work area is a 4 KB naturally
aligned area of storage below the first 4 GB; as such, it may not be
large enough to contain the reports of all changed nodes. The status
value of 1 is used to inform the caller that there are more updates to
report and that it will have to call the
<emphasis>ibm,update-nodes</emphasis> RTAS again to receive them. On
subsequent calls the state variable, which is set to zero on the first
call, is set to the value returned on the previous call, to supply RTAS
with the information it needs to continue from where the previous call
ended.</para>
<para>Upon return, the work area contains, in addition to the state
variable, zero or more operation lists, and logically ends with a
terminator (4 byte word naturally aligned containing 0x00000000). An
operation list consists of an operator (4 bytes naturally aligned) and
zero or more (up to a the maximum number of 4 byte locations remaining in
the work area) operands, each 4 bytes long. An operator consists of a
single byte opcode followed by 3 bytes encoded with the binary value of
the number of operands that follow. An operator with an operand length
field of zero performs no operation, and the opcode of zero is reserved
for the terminator -- thus the terminator can be considered a special
encoding of a no-op operator.</para>
<itemizedlist>
<listitem>
<para>The opcode of 0x01 is used for deleted nodes -- the operands are
the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</listitem>
<listitem>
<para>The opcode of 0x02 is used for updated nodes -- the operands are
the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> values for the updated nodes. The updated
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
properties are obtained using the
<emphasis>ibm,update-properties</emphasis> RTAS call.</para>
</listitem>
<listitem>
<para>The opcode of 0x03 is used for adding nodes -- the operands are
pairs of
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> and
<emphasis role="bold">drc-index</emphasis> values; the
<emphasis role="bold">phandle</emphasis> value denotes the parent node of the node to
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
be added and the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">ibm,drc-index</emphasis> value is passed with the
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis>ibm,configure-connector</emphasis> RTAS call to obtain the
contents of the added node.</para>
</listitem>
</itemizedlist>
<para>To make processing of device tree updates simpler, all opcode 0x01
(delete) operations (if any) are presented prior to all opcode 0x02
(update) operations (if any), and finally any 0x03 (addition) operations
are presented. The
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> operand values are the same
<emphasis role="bold">phandle</emphasis> values as reported by the
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
include the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property in all OF nodes
specified in
<xref linkend="dbdoclet.50569332_80965" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
implement the
<emphasis>ibm,update-nodes</emphasis> RTAS call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_55185" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55185">
<title>Argument Call Buffer
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="4">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,update-nodes</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>32 bit real address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Scope</emphasis>
</para>
</entry>
<entry>
<para>Values per
<xref linkend="dbdoclet.50569332_80965" />.</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error (Purpose does not match the current
partition state)</para>
<para>0: Success</para>
<para>1: More nodes updated -- call again</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS call work area must be 4 KB
long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else
RTAS may return -3 &#8220;Parameter Error&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS for a given value of &#8220;
<emphasis>Scope</emphasis>&#8221; must be formatted as specified in
<xref linkend="dbdoclet.50569332_76526" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76526">
<title>Initial Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" />
<thead>
<row>
<entry>
<para>0x00000000 (State Variable indicates Initial call for
specified
<emphasis>Scope</emphasis>)</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>12 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Upon successful return (non-negative status
value) from
<emphasis>ibm,update-nodes</emphasis> the work area must by formatted as
defined in
<xref linkend="dbdoclet.50569332_64519" />. (Note each entry in
<xref linkend="dbdoclet.50569332_64519" /> is 4 bytes long.)</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64519">
<title>Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" />
<tbody>
<row>
<entry>
<para>State Variable (4 Bytes)</para>
</entry>
</row>
<row>
<entry>
<para>12 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>0 or more operation lists</para>
</entry>
</row>
<row>
<entry>
<para>. . .</para>
</entry>
</row>
<row>
<entry>
<para>Terminator (0x00000000)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS call operation list for the
<emphasis>ibm,update-nodes</emphasis> RTAS call must contain an operator
(4 bytes naturally aligned) and zero or more 4 byte operands up to the
end of the work area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>An operator in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
formatted with, starting at the high order byte, a single byte opcode
followed by 3 bytes encoded with the binary value of the number of
operands that follow.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>An operator in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list with an
operand length field of zero must be considered to perform no
operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The opcode of 0x01 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
used to denote node deletions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>The operands for opcode 0x01 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>The opcode of 0x02 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
used to denote updated nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The operands for opcode 0x02 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> values for the updated nodes that may be used
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
as the
<emphasis>ibm,update-properties</emphasis> RTAS call argument to obtain
the changed properties of the updated node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>The opcode of 0x03 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must used
for the added nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>The operands for opcode of 0x03 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> and
<emphasis role="bold">drc-index</emphasis> value pairs (each value being 4 bytes
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
on a natural boundary totalling 8 bytes for the pair) denoting the parent
node of the added node and the
<emphasis>ibm,configure-connector</emphasis> RTAS call argument to obtain
the contents of the added node respectively.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>All opcode 0x01 (delete) in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
must be presented prior to any opcode 0x02 (update) operations (if
any).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para>All opcode 0x02 (update) in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
must be presented prior to any opcode 0x03 (add) operations (if
any).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para>The work area on subsequent call(s) to
<emphasis>ibm,update-nodes</emphasis> RTAS for the same value of the
<emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> must be formatted as specified in
<xref linkend="dbdoclet.50569332_64422" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64422">
<title>Format of Work Area for Subsequent Calls to
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" />
<thead>
<row>
<entry>
<para>Value of the 1st 16 bytes of the returned work area from
last call to
<emphasis>ibm,update-nodes</emphasis> RTAS that returned status
of 1.</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para>The &#8220;<emphasis>Scope</emphasis>&#8221; argument for the
<emphasis>ibm,update-nodes</emphasis> RTAS call must be one of the values
specified in the scope value column of
<xref linkend="dbdoclet.50569332_80965" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para>For the
<emphasis>ibm,update-nodes</emphasis> RTAS call, the platform must
restrict its reported node updates to those specified in
<xref linkend="dbdoclet.50569332_80965" /> for the value of the specified
<emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_80965">
<title>Nodes That May be Reported by
<emphasis>ibm,update-nodes</emphasis> for a Given Value of the &#8220;
<emphasis>Scope</emphasis>&#8221; Argument</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>Scope Value</para>
</entry>
<entry>
<para>Reportable node types (value of
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> property)</para>
</entry>
<entry>
<para>Supported Opcodes</para>
</entry>
</row>
</thead>
<tbody>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="7">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>Negative values: Platform Resource Reassignment events as
from
<emphasis>event-scan</emphasis> RTAS</para>
</entry>
<entry>
<para>cpu</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>memory</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>ibm,dynamic-reconfiguration-memory</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,plaform-facilities</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,random-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,compression-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,encryption-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry>
<para>
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry morerows="13">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>1 Partition Migration / Hibernation</para>
</entry>
<entry>
<para>
<emphasis>root</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>openprom</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>rtas</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>vdevice</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>cpu</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>cache</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>options</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>memory</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>ibm,dynamic-reconfiguration-memory</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>ibm,platform-facilities</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,random-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,compression-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,encryption-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>2 Activate Firmware</para>
</entry>
<entry>
<para>
<emphasis>rtas</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_40069">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,update-properties</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call is used to report updates to the properties changed
due to a massive platform reconfiguration such as when the partition is
migrated between machines. This RTAS call reports changes in the node
specified by the phandle value in the work area passed using the Work
Area Address argument. The phandle value may be that of a critical node
that the caller is interested in or one reported by
<emphasis>ibm,update-nodes</emphasis> RTAS call. These changes may include
any combination of new values, deleted and added properties. Updates for
a given node are retained until the platform is subsequently
reconfigured, and remain available to subsequent calls to
<emphasis>ibm,update-nodes</emphasis>.</para>
<para>There may be more changes than can be reported in a single 4 K work
area. In this case, the RTAS call returns with a status of 1 &#8220;More
properties updated -- call again&#8221;. On the first call, the second
word of the work area contains the value 0 specifying that the RTAS call
is to start with the first changed property for the specified updated
node. On a call with a status value of 1, the first sixteen (16) bytes of
the work area contain values that, when subsequently supplied in the work
area of another call to
<emphasis>ibm,update-properties</emphasis> RTAS, specify that the call
returns the updated property data for properties after those reported in
the previous call.</para>
<para>A single updated property value string may exceed the capacity of a
single 4 K work area. In that case, the updated property value descriptor
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
for the property appears in the work area of multiple sequential calls to
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis>ibm,update-properties</emphasis> RTAS. When the updated property
value descriptor contains the final data for the property value, the
property string length field of the updated property value descriptor is
a positive number. When the updated property value descriptor contains
either the initial or interim data for the property value, the updated
property string length field is a negative number denoting the twos
complement of the length of the updated property string contained in the
work area. The data value strings for a given property name are
concatenated until the final updated property value descriptor is
processed.</para>
<para>The first value returned, with an updated property name string of
NULL, is always the node&#8217;s name (for example: full path ||
<emphasis>name</emphasis> property value || @ unit address) even if there
has been no change.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
implement the
<emphasis>ibm,update-properties</emphasis> RTAS call using the argument
call buffer defined by
<xref linkend="dbdoclet.50569332_63317" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_63317">
<title>Argument Call Buffer
<emphasis>ibm,update-properties</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="4">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,update-properties</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>32 bit real address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Scope</emphasis>
</para>
</entry>
<entry>
<para>Values per
<xref linkend="dbdoclet.50569332_71049" />.</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error (Purpose does not match the current
partition state)</para>
<para>0: Success</para>
<para>1: More properties updated -- call again</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-properties</emphasis> RTAS call must be 4 KB long
aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS
may return -3 &#8220;Parameter Error&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The work area on the first call to
<emphasis>ibm,update-properties</emphasis> RTAS for a given updated node
must be formatted as specified in
<xref linkend="dbdoclet.50569332_84989" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_84989">
<title>Initial Format of Work Area for
<emphasis>ibm,update-properties</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" />
<thead>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> of updated node containing updated
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
properties to be reported (4 bytes)</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x00000000 (Indicates Initial call for specified
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis>)</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
</row>
<row>
<entry>
<para>8 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Upon successful return (non-negative status
value) from
<emphasis>ibm,update-properties</emphasis> the work area must by formatted
as defined in
<xref linkend="dbdoclet.50569332_72959" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_72959">
<title>Return Format of Work Area for
<emphasis>ibm,update-properties</emphasis></title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" />
<colspec colname="c2" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis>Description</emphasis>
</para>
</entry>
<entry>
<para>Comments</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> of updated node containing updated
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
properties to be reported.</para>
</entry>
<entry>
<para>4 Bytes</para>
</entry>
</row>
<row>
<entry>
<para>State Variable</para>
<para>(to be returned if status argument value = 1)</para>
</entry>
<entry>
<para>4 Bytes</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>8 bytes</para>
</entry>
</row>
<row>
<entry>
<para>Number of properties reported in the work area</para>
</entry>
<entry>
<para>4 Bytes</para>
<para>The number (N) of updated property value descriptors that
follow -- see below</para>
</entry>
</row>
<row>
<entry>
<para>N updated property value descriptors</para>
</entry>
<entry>
<para>Each updated property value descriptor is formatted
as:</para>
<para>&#160;</para>
<para>Null terminated string indicating the name of the updated
property.</para>
<para>followed by:</para>
<para>Value Descriptor -- 4 Bytes decoded as</para>
<para>&#160;</para>
<para>0x00000000 Name only property (
<emphasis role="bold"><literal>&#8220;encode-null&#8221;</literal></emphasis>) no value
follows</para>
<para>&#160;</para>
<para>0x80000000 The property is to be deleted no value
follows</para>
<para>&#160;</para>
<para>Other positive values are the length (M) of the
immediately following property value string that completes the
update of the property value.</para>
<para>&#160;</para>
<para>Other negative values are the twos complement of the
length (M) of the immediately following property value string
that either starts or continues the update of the property
value with the remainder in the work area of subsequent call(s)
to
<emphasis>ibm,update-properties</emphasis>.</para>
<para>&#160;</para>
<para>Followed by:</para>
<para>0-M bytes of property value string.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Upon successful return (non-negative status
value) from
<emphasis>ibm,update-properties</emphasis> when the State Variable had
been 0x00000000, the first updated property descriptor must describe the
fully qualified path name of the node specified by the phandle argument
in the work buffer; the three fields of this updated property descriptor
are:</para>
<itemizedlist>
<listitem>
<para>Property name string is as from
<emphasis>encode-null</emphasis></para>
</listitem>
<listitem>
<para>Value descriptor is the 4 byte binary length of the value
string</para>
</listitem>
<listitem>
<para>Value string is the fully qualified path name as from the node
name string returned by the open firmware
<emphasis>package-to-path</emphasis> client interface call.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The work area on subsequent call(s) to
<emphasis>ibm,update-properties</emphasis> RTAS for a given updated node
must be formatted as specified in
<xref linkend="dbdoclet.50569332_96468" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_96468">
<title>Format of Work Area for Subsequent Calls to
<emphasis>ibm,update-properties</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" />
<thead>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold">phandle</emphasis> of updated node containing updated
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
properties to be reported (4 Bytes)</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Value from last call to
<emphasis>ibm,update-properties</emphasis> RTAS that returned
status of 1 (12 bytes).</para>
</entry>
</row>
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-properties</emphasis> RTAS call, the platform must
restrict its reported property updates to those specified in
<xref linkend="dbdoclet.50569332_71049" /> for the value of the specified
<emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>For the
<emphasis>ibm,update-properties</emphasis> RTAS call, the platform must
return a
<emphasis>Status</emphasis> of -3 (Parameter Error) for an unrecognized
value of the &#8220;Scope&#8221; argument.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71049">
<title>Properties of the Nodes That May Be Reported by
<emphasis>ibm,update-properties</emphasis> for a &#8220;
<emphasis>Scope</emphasis>&#8221;</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>Scope Value</para>
</entry>
<entry>
<para>Reportable node types (value of
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> property)</para>
</entry>
<entry>
<para>Property Name</para>
</entry>
</row>
</thead>
<tbody>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="6">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>All negative values: Resource Reassignment events as from
event-scan RTAS</para>
</entry>
<entry>
<para>/memory</para>
</entry>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para><emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis></para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
</row>
<row>
<entry>
<para>ibm,dynamic-reconfiguration-memory</para>
</entry>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis></para>
<para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis></para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
</row>
<row>
<entry>
<para>cpu</para>
</entry>
<entry>
<para>&#8220;ibm,associativity&#8221;</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry>
<para>
<emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry morerows="31">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>1 Partition Migration / Hibernation</para>
</entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="18">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>root</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,model-class&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,extended-clock-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;system-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221;</literal></emphasis>
</para>
</entry>
</row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
</para>
</entry>
</row>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,aix-diagnostics&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,diagnostic-lic&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,ignore-hp-po-fails-for-dlpar&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,managed-address-types&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,service-indicator-mode&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>openprom</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry morerows="8">
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>rtas</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;power-on-max-latency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,max-associativity-domains&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,configure-kernel-dump-version&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,read-slot-reset-state-functions&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,configure-pe&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,change-msix-capable&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="1">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>vdevice</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
</para>
</entry>
</row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
</para>
</entry>
</row>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>children of the
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>vdevice</literal></emphasis> node</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry morerows="31">
<para>1 Partition Migration / Hibernation</para>
<para>&#160;</para>
</entry>
<entry morerows="20">
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>cpu</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;d-cache-sets&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;d-cache-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;i-cache-sets&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;i-cache-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;bus-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,extended-bus-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>
&#8220;ibm,extended-clock-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;timebase-frequency&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;l2-cache&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;performance-monitor&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>TLB properties (See
<xref linkend="LoPAR.DeviceTree" />)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;slb-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,tbu40-offset&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,pi-features&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,spurr&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,pa-optimizations&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,dfp&#8221;</literal></emphasis> (sign bit
only)</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>&#8220;ibm,sub-processors&#8221;</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
</row>
<row>
<entry morerows="4">
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>cache</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;d-cache-sets&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;d-cache-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;i-cache-sets&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;i-cache-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>l2-cache</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>options</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,dasd-spin-interval&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>memory</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,dynamic-reconfiguration-memory</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para><emphasis role="bold"><literal>&#8220;ibm,associativity-lookup-arrays&#8221;</literal></emphasis></para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
</row>
<row>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis></para>
<para><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis></para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>only the associativity list index fields</para>
</entry>
</row>
<row>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para><emphasis role="bold"><literal>&#8220;ibm,memory-preservation-time&#8221;</literal></emphasis></para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>/chosen</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis>
</para>
<para>byte 3 (I/O Super Page Option support parameters)</para>
</entry>
</row>
<row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="3">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>1 Partition Migration / Hibernation</para>
<para>&#160;</para>
</entry>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para>2 Activate Firmware</para>
</entry>
<entry>
<para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<emphasis role="bold"><literal>rtas</literal></emphasis>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</para>
</entry>
<entry>
<orderedlist>
<listitem>
<para>Any
<emphasis role="bold"><literal>/rtas</literal></emphasis> node property as defined per LoPAR
remains invariant.</para>
</listitem>
<listitem>
<para>Any
<emphasis role="bold"><literal>/rtas</literal></emphasis> node property or definition
extension, except for the value of a function token property*,
may change (provided that the client program has indicated
support for such property or definition extension) including
the following:</para>
<para>
<emphasis role="bold"><literal>&#8220;ibm,read-slot-reset-state-functions&#8221;
&#8220;ibm,configure-pe&#8221;</literal></emphasis>
</para>
</listitem>
</orderedlist>
<para>*NOTE: This exception mandates that if an RTAS function
token property survives a firmware activation, the token value
of that RTAS function call does not change.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_67111">
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<title><emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call</title>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>This RTAS call is used to register and unregister with the platform
a data structure describing kernel dump information. This dump
information is preserved as needed by the platform in support of a
platform assisted kernel dump option.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
option:</emphasis> The platform must implement the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call using the
argument call buffer defined by
<xref linkend="dbdoclet.50569332_24141" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24141">
<title>Argument Call Buffer
<emphasis>ibm,configure-kernel-dump</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<tbody>
<row>
<entry>
<para>Parameter Type</para>
</entry>
<entry>
<para>Name</para>
</entry>
<entry>
<para>Values</para>
</entry>
</row>
<row>
<entry morerows="5">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,configure-kernel-dump</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Command</emphasis>
</para>
</entry>
<entry>
<para>1: Register for future kernel dump</para>
<para>2: Unregister for future kernel dump</para>
<para>3: Complete/Invalidate current kernel dump</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work_buffer_address</emphasis>
</para>
</entry>
<entry>
<para>When command is 1: Register for future kernel dump,
points to a structure as defined in
<xref linkend="dbdoclet.50569332_76933" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work_buffer_length</emphasis>
</para>
</entry>
<entry>
<para>Length of Kernel Dump Memory Structure when defined
above</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>0: Success</para>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error</para>
<para>-9: Dump Already Registered</para>
<para>-10: Dump Active</para>
<para>990x:Extended Delay</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
option:</emphasis> The work-buffer address and work-buffer-length for the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call must point to an
RMR-memory buffer that contains the structures described in
<xref linkend="dbdoclet.50569332_76933" />, whenever the command is 1,
register for future kernel dump; otherwise the call may return -3,
&#8220;Parameter Error.&#8221;</para>
<para>The Dump Memory Structure specified in
<xref linkend="dbdoclet.50569332_76933" /> is passed by the operating
system during a
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call. It is also
reported by the platform using the
<emphasis>ibm,kernel-dump</emphasis> RTAS property after a dump has been
initiated.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76933">
<title>Kernel Assisted Dump Memory Structure</title>
<tgroup cols="5">
RTAS: fix "Kernel Assisted Dump Memory Structure" table formatting We currently have 5 columns where the last 2 are defined to only use 1% of the table width, causing the corresponding row entries to overrun the table and use excessive vertical space. Define the column widths as 1*/1*/1*/2*/2* instead, since the last 2 columns are used for the value descriptions. Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
6 years ago
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="1*" />
<colspec colname="c3" colwidth="1*" />
<colspec colname="c4" colwidth="2*" />
<colspec colname="c5" colwidth="2*" />
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<thead>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Header</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Offset</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Number of Bytes</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Value</para>
</entry>
</row>
<row>
<entry>
<para>0x0</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Format Version = 0x00000001</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of Kernel Dump Sections</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Status Flags</para>
<para>A bit mask with value</para>
<para>0x8000 = Dump performed (Set to 0 by caller of the
ibm,configure-kernel-dump call)</para>
<para>0x4000 = Dump was triggered by the previous system boot
(set by platform)</para>
<para>0x2000 = Dump error occurred (set by platform)</para>
<para>All other bits reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Offset to first Kernel Dump Section, offset from the
beginning of the Structure</para>
</entry>
</row>
<row>
<entry>
<para>0xc</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of bytes in a block of the dump-disk, if data to
be written to a dump-disk, If not, should be set to 0
(indicating the no disk dump option.)</para>
</entry>
</row>
<row>
<entry>
<para>0x10</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Starting block# offset on dump-disk (set to 0 for the no
disk dump option)</para>
</entry>
</row>
<row>
<entry>
<para>0x18</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of blocks on dump-disk usable for dump (set to 0
for the no disk dump option)</para>
</entry>
</row>
<row>
<entry>
<para>0x20</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Offset from start of structure to a Null-terminated
Dump-disk path string (set to 0 for the no disk dump
option)</para>
</entry>
</row>
<row>
<entry>
<para>0x24</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Maximum time allowed (milliseconds) after
Non-Maskable-Interrupt for the OS to call
<emphasis>ibm,configure-kernel-dump</emphasis>
<emphasis>Function</emphasis> 2 (unregister) to prevent an
automatic dump-reboot (set to 0 to disable the automatic
dump-reboot function)</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Dump-disk Path String</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Offset specified above</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Varies</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Null-terminated Dump-disk path string specifying the
dump-disk. If no disk dump option is indicated, this section is
not included.</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>First Kernel Dump Section</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Offset specified above</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Request Flags:</para>
<para>A bit-mask</para>
<para>Bit 0x00000001 When set, firmware to copy source data to
partition memory. This option must be selected if no disk dump
option is indicated.</para>
<para>All other bit values reserved</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+4</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Source Data type, describes section of dump memory being
described</para>
<para>0x0001 = CPU State Data</para>
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
<para>0x0011 = Real Mode Region</para>
<para>0x0012 = Dump OS identified string (identifies that the
dump is for a particular OS type and version)</para>
<para>0x0100 - 0xFFFF OS defined source types</para>
<para>All Other values reserved</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+6</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Error Flags (set by platform)</para>
<para>Bit mask</para>
<para>0x8000 = Invalid section data type</para>
<para>0x4000 = Invalid source address</para>
<para>0x2000 = Requested section length exceeds source</para>
<para>0x1000 = Invalid partition destination address</para>
<para>0x0800 = Partition memory destination too small</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+8</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Source address (logical address if section came from
partition memory, or byte offset if section is platform
memory)</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+16</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Requested data length, represents number of bytes to
dump</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+24</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Actual data length, number of bytes dumped</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+32</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Destination address, logical address used for sections
not written to disk by the platform, always required for a Real
mode region section and for all sections when the no disk dump
option is used.</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Subsequent Sections</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Previous Section Start+40</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Start of Next Section</para>
</entry>
<entry nameend="c5" namest="c4">
<para>A total of up to nine additional 40 bytes sections with
values as described in the First Section may be specified so
long as the entire structure does not exceed 512 bytes for
version 1.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis>ibm,os-term</emphasis> RTAS call, or on a system reset without
an
<emphasis>ibm,nmi-interlock</emphasis> RTAS call, if the platform has a
dump structure registered through the
<emphasis>ibm,configure-kernel-dump</emphasis> call, the platform must
process each registered kernel dump section as required and, when
available, present the dump structure information to the operating system
through the
<emphasis role="bold"><literal>&#8220;ibm,kernel-dump&#8221;</literal></emphasis> property, updated with
status for each dump section, until the dump has been invalidated through
the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
RTAS: fix typos referencing ibm,configure-kernel-dump Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
6 years ago
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
register or unregister for a dump while a dump is currently active, the
platform must return a
<emphasis>Status</emphasis> of -9, &#8220;Dump Active&#8221; indicating
that a dump has been copied by the platform and a call must be made to
complete/invalidate the active dump before another call to register or
unregister a dump can be completed successfully.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
RTAS: fix typos referencing ibm,configure-kernel-dump Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
6 years ago
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
register a dump after a dump has already been registered by a call, the
platform must return a
<emphasis>Status</emphasis> of -8, &#8220;Dump Already Registered&#8221;
unless an intervening call was made to invalidate the previously
registered dump.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> Partition memory not specifically mentioned in the call
structure must be preserved by the platform at the same location as
existed prior to the os termination or platform reboot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> The platform must present the RTAS property,
<emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis> in the
OF device tree, which describes how much space is required to store dump
data for the firmware provided dump sections, where the firmware defined
dump sections are:</para>
<itemizedlist>
<listitem>
<para>0x0001 = CPU State Data</para>
</listitem>
<listitem>
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> The platform must present the RTAS property,
<emphasis role="bold"><literal>&#8220;ibm-configure-kernel-dump-version&#8221;</literal></emphasis> in
the OF device tree.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> After a dump registration is disabled (for example, by
a partition migration operation), calls to
<emphasis>ibm,os-term</emphasis> must return to the OS as though a dump
was not registered.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> The intended flow of interactions
that utilize this call is as follows:</para>
<orderedlist>
<listitem>
<para>The OS registers sections of memory for dump preservation during
OS initialization</para>
</listitem>
<listitem>
<para>The OS terminates abnormally</para>
</listitem>
<listitem>
<para>The Platform moves registered sections of memory as instructed
during dump registration.</para>
</listitem>
<listitem>
<para>The Partition reboots and provides the prior registration data
in the device tree.</para>
</listitem>
<listitem>
<para>The OS writes the preserved memory regions to disk before using
those memory regions for regular use</para>
</listitem>
<listitem>
<para>The OS completes/invalidates current dump status.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_14137">
<title>DMA Window Manipulation Calls</title>
<para>DMA windows for a PE can be changed by the OS when the platform
implements the Dynamic DMA Windows (DDW) option for a PE. The occurrence
of the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property in any node
of the OF Device Tree indicates that the platform implements the DDW
option, but that property is required to be in the bridge above a PE in
order for the DDW RTAS call to be applicable for the PE. That is, DDW may
be applicable to some PEs in a platform and not for others.</para>
<para>The platform may implement the DDW RTAS calls even when the OS does
not support these, because they are not required to be used by the OS,
because there is always a default window initially allocated below 4 GB,
as specified by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property. During
partition migration, these RTAS calls may come and go, but so will the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property as the
nodes in which those are supported come or go.</para>
<para>The following is an example of how an OS may grab all DMA window
resources allocated for a PE:</para>
<orderedlist>
<listitem>
<para>If the default window (as specified by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for the PE) is
not needed, then call
<emphasis>ibm,remove-pe-dma-window</emphasis> for the PE, specifying the
default window LIOBN, to make the maximum resources available for the
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>
</listitem>
<listitem xml:id="dbdoclet.50569332_89344">
<para>Call
<emphasis>ibm,query-pe-dma-window</emphasis> for the PE to get the
<emphasis>Windows Available</emphasis> and
<emphasis>PE TCEs</emphasis> available for the PE. If the
<emphasis>Windows Available</emphasis> field indicates 1 or more and the
<emphasis>PE TCEs</emphasis> field is non-zero, then continue.</para>
</listitem>
<listitem>
<para>Call <emphasis>ibm,create-pe-dma-window</emphasis> for the PE, specifying the
size based on the
<emphasis>PE TCEs</emphasis> field obtained from the
<emphasis>ibm,query-pe-dma-window</emphasis> RTAS call in step
<xref linkend="dbdoclet.50569332_89344" /> and on the I/O page size being
specified.</para>
</listitem>
<listitem>
<para>If the <emphasis>Windows Available</emphasis> field indicated 2 or more in step
<xref linkend="dbdoclet.50569332_89344" />, then go back to step
<xref linkend="dbdoclet.50569332_89344" /> and repeat, otherwise
finished.</para>
</listitem>
</orderedlist>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> The general expectation
is that if the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property exists for
a PE, that the OS will be able to generate one or more windows whose
total size is larger than what is available via the default window. This
requires either additional TCEs being available or that I/O page sizes
other than 4 KB are available and the PE can use the largest I/O page
size (the default window using only the 4 KB I/O page size). If not, then
removing the default window would only allow re-allocation of the same
size window at a different bus address (that is, same number of TCEs and
same I/O page size). However, it may be possible for this to happen, in
which case the platform may indicate that DDW is available to a PE, but
removal of the default window will only allow creation of the same size
window. An example is when a larger I/O page size is available but only
the TCEs in the default window are available, and the PE cannot make use
of the larger page size.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
platform must implement all of the following RTAS calls:
<emphasis>ibm,query-dma-window</emphasis>,
<emphasis>ibm,create-dma-window</emphasis>, and
<emphasis>ibm,remove-dma-window.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
platform must provide the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property in the OF
Device Tree in the bridge above each PE for which the DDW option is
supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
software must not call the
<emphasis>ibm,query-dma-window</emphasis>,
<emphasis>ibm,create-dma-window</emphasis>, or
<emphasis>ibm,remove-dma-window</emphasis> RTAS calls in the absence of
the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property for the PE,
otherwise the call returns a
<emphasis>Status</emphasis> of -3 (Parameter error), and when the property
does exist, software must use the token values specified in the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property for these
RTAS calls.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
platform must provide a default DMA window for each PE, and all of the
following must be true:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>The window is defined by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
device tree.</para>
</listitem>
<listitem>
<para>The window is defined with 4 KB I/O pages.</para>
</listitem>
<listitem>
<para>The window is located entirely below 4 GB.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_79382">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
The platform must remove any DMA windows created by the
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call for a PE and must
restore the default DMA window (if it was removed) for the PE, as
originally defined by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> properties for the PE,
in each of the following cases:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>On a reboot of the partition</para>
</listitem>
<listitem>
<para>On a DR isolate operation that encompasses the PE</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_72212">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_14137"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
In Requirement
<xref linkend="dbdoclet.50569332_79382" />, the platform must provide the
same LIOBN, location, and size as specified in the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
Device Tree for the device.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569332_99826">
<title><emphasis>ibm,query-pe-dma-window</emphasis></title>
<para>This RTAS call allows for the discovery of the resources necessary
to make a successful subsequent call to
<emphasis>ibm,create-dma-window</emphasis>.</para>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>If the <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call is made with Number Outputs
equal to 6, and the <emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis>
property does not include list index of 3,
then the call will return a Status of -3 (Invalid Parameter).</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>RTAS must implement a
<emphasis>ibm,query-pe-dma-window</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_53901" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_53901">
<title>Argument Call Buffer
<emphasis>ibm,query-pe-dma-window</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="5">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,query-pe-dma-window</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>5 or 6. The value 6 may be used when the ibm,ddw-extensions property
in the PHB node specified by this call indicates support for a 64-bit value of
PE TCEs. See <xref linkend="dbdoclet.50569332_25585" />.</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</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>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<entry morerows="5">
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>0: Success</para>
<para>-1: Hardware Error</para>
<para>-3: Parameter error</para>
</entry>
</row>
<row>
<entry>
<para>Windows Available</para>
</entry>
<entry>
<para>Number of additional DMA windows that can be created for
this PE. If the value is 0 and the default window (as specified
by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for
the PE) has not been yet removed via the
<emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call for that
window, and if the default window is not needed, then removal
of the default window makes at least one window
available.</para>
</entry>
</row>
<row>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>PE TCEs hi</para>
</entry>
<entry>
<para>Represents the most-significant 32-bits of the largest contiguous
block of TCEs allocated specifically for (that is, are reserved for) this PE.</para>
</entry>
</row>
<row>
<entry>
<para>PE TCEs lo</para>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</entry>
<entry>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<para>Represents the least-significant 32-bits of the largest contiguous block
of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<xref linkend="dbdoclet.50569332_91197" />.</para>
</entry>
</row>
<row>
<entry>
<para>IO Page Sizes</para>
</entry>
<entry>
<para>I/O Page Size Support. I/O page sizes supported for this
PE. This is a bit significant field, defined as follows:</para>
<para>Bits 0 - 23 reserved</para>
<para>24 = 16 GB page size supported</para>
<para>25 = 256 MB page size supported</para>
<para>26 = 128 MB pages supported</para>
<para>27 = 64 MB page size supported</para>
<para>28 = 32 MB page size supported</para>
<para>29 = 16 MB page size supported</para>
<para>30 = 64 KB page size supported</para>
<para>31 = 4 KB page size supported</para>
</entry>
</row>
<row>
<entry>
<para>Migration Capable</para>
</entry>
<entry>
<para>H_MIGRATE_DMA Mask. Mask to indicate for which page sizes
(as specified in the I/O Page Size Support field), that
H_MIGRATE_DMA is supported (for this PE). This is a bit
significant field, with the bits defined to align to the bits
in the I/O Page Size Support field.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_91197">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
TCE resources returned in the
<emphasis>PE TCEs</emphasis> parameter of the
<emphasis>ibm,query-dma-window</emphasis> RTAS call must be allocated to
the PE specified by the PE configuration address specified in the call,
and must be available to a subsequent
<emphasis>ibm,create-dma-window</emphasis> RTAS call for that PE.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_49009">
<title><emphasis>ibm,create-pe-dma-window</emphasis></title>
<para>This call allows the creation of a new DMA window, given the size
of the DMA window, I/O page size, and the PE to which it is associated.
The return from the call includes the LIOBN of the new DMA window, the
starting I/O address of the DMA window, and size.</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> Software is expected to
not attempt to create a DMA window that is larger than possible, or
create more DMA windows than is possible, otherwise the
<emphasis>ibm,create-pe-dma-window</emphasis> will return a
<emphasis>Status</emphasis> of -3 (Parameter Error). Thus, the OS is
expected to use the
<emphasis>ibm,query-pe-dma-window</emphasis> first and not ask to create a
window that consumes more resources than those that are available to the
PE.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_49009"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
implement the
<emphasis>ibm,create-dma-window</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_26269" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26269">
<title>Argument Call Buffer
<emphasis>ibm,create-pe-dma-window</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="7">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,create-pe-dma-window</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Config_addr</emphasis>
</para>
</entry>
<entry>
<para>PE configuration address (Register fields set to
0)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>PHB_Unit_ID_Hi</emphasis>
</para>
</entry>
<entry>
<para>Represents the most-significant 32-bits of the Unit ID of
the PHB that corresponds to the
<emphasis>config_addr</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>PHB_Unit_ID_Low</emphasis>
</para>
</entry>
<entry>
<para>Represents the least-significant 32-bits of the Unit ID
of the PHB that corresponds to the
<emphasis>config_addr</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>I/O Page Size</para>
</entry>
<entry>
<para>The value n, where 2
<emphasis>n</emphasis> is the requested I/O page size. Only page
sizes obtained from the
<emphasis>ibm,query-pe-dma-window</emphasis> RTAS call for the
PE are allowed. Values of n from 0-11 are invalid.</para>
</entry>
</row>
<row>
<entry>
<para>Requested Window Size</para>
</entry>
<entry>
<para>The value n, where 2
<emphasis>n</emphasis> is the requested DMA window size.</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>990x: Extended delay, where x is a number 0-5 (see
text)</para>
<para>0: Success (window created)</para>
<para>-1: Hardware Error</para>
<para>-2: Busy, try again later</para>
<para>-3: Parameter Error</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>LIOBN</emphasis>
</para>
</entry>
<entry>
<para>LIOBN of the DMA window created by this call, if any. If
no DMA window was created (that is, if the
<emphasis>Status</emphasis> is not 0), then this field is
present but not used.</para>
</entry>
</row>
<row>
<entry>
<para>I/O Starting Address Hi</para>
</entry>
<entry>
<para>Represents the most-significant 32-bits of the starting
address on the I/O bus for the DMA window created by this call,
if any. If no DMA window was created (that is, if the
<emphasis>Status</emphasis> is not 0), then this field is
present but not used.</para>
</entry>
</row>
<row>
<entry>
<para>I/O Starting Address Low</para>
</entry>
<entry>
<para>Represents the least-significant 32-bits of the starting
address on the I/O bus for the DMA window created by this call,
if any. If no DMA window was created (that is, if the
<emphasis>Status</emphasis> is not 0), then this field is
present but not used.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_49009"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call must return a
<emphasis>Status</emphasis> of 0 (Success) only if a window with the
requested attributes is created, and must not create a new window if a
non-0
<emphasis>Status</emphasis> is returned.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569332_60545">
<title><emphasis>ibm,remove-pe-dma-window</emphasis></title>
<para>This RTAS call allows for the removal of PE DMA windows, including
those created with the
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call as well as the
default window specified by the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property for the PE. All
created DMA windows will be removed by the platform, and the default DMA
window restored, on a partition reboot, on a DR isolate operation (see
Requirement
<xref linkend="dbdoclet.50569332_79382" /> and
<xref linkend="dbdoclet.50569332_72212" />), or if the last remaining DMA
window for the PE is removed and that window is not the default DMA
window (see Requirements
<xref linkend="dbdoclet.50569332_40989" /> and
<xref linkend="dbdoclet.50569332_34916" />). After removal of a DMA
window, software needs to use the
<emphasis>ibm,query-pe-dma-window</emphasis> RTAS call to find out what
resources are available to the PE for subsequent
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
implement the
<emphasis>ibm,remove-dma-window</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_36074" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_36074">
<title>Argument Call Buffer
<emphasis>ibm,remove-pe-dma-window</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="3">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,remove-pe-dma-window</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>LIOBN</emphasis>
</para>
</entry>
<entry>
<para>LIOBN of the DMA window to be removed.</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>0: Success</para>
<para>-1: Hardware Error</para>
<para>-3: Parameter error</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> The caller
of the
<emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call must assure that
the TCE table specified by the
<emphasis>LIOBN</emphasis> field does not contain any valid mappings at
the time of the call (that is, that the window is not being used).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_40989">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
The platform must
restore the default DMA window for the PE on a call to the
<emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call when all of the
following are true:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>The call removes the last DMA window remaining for the
PE.</para>
</listitem>
<listitem>
<para>The DMA window being removed is not the default window.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569332_34916">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
In Requirement
<xref linkend="dbdoclet.50569332_40989" />, the platform must provide the
same LIOBN, location, and size as specified in the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the OF
Device Tree for the PE.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_ext_to_ddw">
<title>Extensions to Dynamic DMA Windows</title>
<para>Platforms supporting the DDW option implement extensions described
in this section. These extensions include: adding the
<emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> property see
<xref linkend="LoPAR.DeviceTree" /> to those nodes that include the
<emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis> property, and
implementing the functional extensions specified for the architectural
level in
<xref linkend="dbdoclet.50569332_25585" />. The
<emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> property value is a
list of integers the first integer indicates the number of extensions
implemented and subsequent integers, one per extension, provide a value
associated with that extension. Thus the property value is designed to
grow over time in such a way as to enable earlier client programs to
ignore later firmware extensions and later client programs to operate on
back level firmware. For this level of compatibility to work, the client
code needs to ignore extensions beyond what were defined when the client
code was written, and be prepared to operate on back level platforms t at
do not implement all the extensions that were defined when the client
code was written.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_25585">
<title>DDW Option Extensions</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">DDW Option LoPAR or PAPR Level</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">
<emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> list
index</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>2.7</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>Token of the i
<emphasis>bm,reset-pe-dma-windows</emphasis> RTAS Call</para>
</entry>
</row>
Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
<row>
<entry>
<para>2.7</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>Value of 1 indicates the OS may invoke RTAS <emphasis>ibm,query-pe-dma-window</emphasis>
with Number Outputs equal to 6. Other values are reserved.</para>
</entry>
</row>
Initial repo priming from IBM Internal tree. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
7 years ago
</tbody>
</tgroup>
</table>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_to_ddw"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For compatibility with changing extensions to the Dynamic DMA
Windows (DDW) option:</emphasis> The client program must ignore extensions
as represented by
<emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis> value list integers
beyond those defined when the client code was written.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_to_ddw"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For compatibility with changing extensions to the Dynamic DMA
Windows (DDW) option:</emphasis> The client program must be prepared to
operate on back level platforms that do not implement all the extensions
that were defined when the client code was written, including no
extensions at all.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec_reset_pe_dma_windows">
<title><emphasis>ibm,reset-pe-dma-windows</emphasis></title>
<para>The
<emphasis>ibm,reset-dma-windows</emphasis> call resets the TCE table
allocation for the PE to its boot time value as communicated in the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> OF Device Tree property
in the for the PE.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
level 2.7:</emphasis> RTAS must implement the
<emphasis>ibm,reset-dma-windows</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_68052" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_68052">
<title>Argument Call Buffer
<emphasis>ibm,reset-pe-dma-windows</emphasis></title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="5">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>config_addr</emphasis>
</para>
</entry>
<entry>
<para>PE configuration address</para>
</entry>
</row>
<row>
<entry>
<para>PHB_Unit_ID_HI</para>
</entry>
<entry>
<para>Represents the most-significant 32-bits of the Unit ID of
the PHB that corresponds to the config_addr</para>
</entry>
</row>
<row>
<entry>
<para>PHB_Unit_ID_Low</para>
</entry>
<entry>
<para>Represents the least-significant 32-bits of the Unit ID
of the PHB that corresponds to the config_addr</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>0: Success</para>
<para>-1: Hardware Error</para>
<para>-2: Busy, Try again later</para>
<para>-3: Parameter error</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
level 2.7:</emphasis> The caller of the
<emphasis>ibm,reset-pe-dma-windows</emphasis> RTAS call must assure that
the TCE table(s) assigned to the PE specified by the
<emphasis>config_addr</emphasis> field contain no valid mappings at the
time of the call (that is, that the window(s) is not being used).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
level 2.7:</emphasis> On a call to
<emphasis>ibm,restore-pe-dma-windows</emphasis>, the platform must
restore the default DMA window per the values provided in the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> Tree property
in the for the PE (same LIOBN, location, and size).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
</section>