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.
6036 lines
263 KiB
XML
6036 lines
263 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Copyright (c) 2016 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xl="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:lang="en"
|
|
xml:id="sec_get_indices_rtas_call">
|
|
|
|
<title><emphasis>ibm,get-indices</emphasis> Call</title>
|
|
|
|
<para>The RTAS function
|
|
<emphasis>ibm,get-indices</emphasis> is used to obtain the indices and
|
|
location codes for a specified indicator or sensor token. It allows for
|
|
obtaining the list of indicators and sensors dynamically and therefore
|
|
assists in any Dynamic Reconfiguration operation that involves indicators
|
|
and sensors being added or deleted from the platform (unlike the
|
|
<emphasis role="bold"><literal>/rtas</literal></emphasis> node
|
|
<emphasis role="bold"><literal>“</literal></emphasis><emphasis><literal><vendor></literal></emphasis><emphasis role="bold"><literal>,indicator-</literal></emphasis><emphasis><literal><token></literal></emphasis><emphasis role="bold"><literal>”</literal></emphasis>,
|
|
<emphasis role="bold"><literal>“</literal></emphasis><emphasis><literal><vendor></literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal><token></literal></emphasis><emphasis role="bold"><literal>”</literal></emphasis>,
|
|
and <emphasis role="bold"><literal>“ibm,environmental-sensor”</literal></emphasis> properties).
|
|
This call also allows discontiguous indices for a particular indicator or
|
|
sensor type (unlike the
|
|
<emphasis role="bold"><literal>“rtas-indicators”</literal></emphasis>,
|
|
<emphasis role="bold"><literal>“rtas-sensors”</literal></emphasis>, and
|
|
<emphasis role="bold"><literal>
|
|
“ibm,environmental-sensor”</literal></emphasis> properties).</para>
|
|
<para>This RTAS call is not used for DR indicators (9001, 9002, and 9003)
|
|
or DR sensors (9003). See the following sections in the DR chapter for more
|
|
information:
|
|
<xref linkend="LoPAR.Virtualization" /> and
|
|
<xref linkend="LoPAR.Virtualization" />.</para>
|
|
<para>It may require several calls to the
|
|
<emphasis>ibm,get-indices</emphasis> RTAS routine to get the entire list of
|
|
indicators or sensors of a particular type. Each call may specify a
|
|
different work area.</para>
|
|
<para>The OS may not interleave calls to
|
|
<emphasis>ibm,get-indices</emphasis> for different indicator or sensor
|
|
types. Other standard RTAS locking rules apply.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For all DR options:</emphasis> The RTAS function
|
|
<emphasis>ibm,get-indices</emphasis> must implement the argument call buffer
|
|
defined by
|
|
<xref linkend="dbdoclet.50569332_50675" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_50675">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,get-indices</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="7">
|
|
<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>“ibm,get-indicator-indices-types”</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>“ibm,get-sensor-indices-types”</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>“ibm,get-indicator-indices-types”</literal></emphasis> property,
|
|
it must not be included in the
|
|
<emphasis role="bold"><literal>“</literal></emphasis><emphasis><literal><vendor></literal></emphasis><emphasis><literal>,indicator-</literal></emphasis><emphasis><literal><token></literal></emphasis><emphasis role="bold"><literal>”</literal></emphasis>
|
|
property and must not be included in the
|
|
<emphasis role="bold"><literal>“rtas-indicators”</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>“ibm,get-sensor-indices-types”</literal></emphasis> property, it
|
|
must not be included in the
|
|
<emphasis role="bold"><literal>“</literal></emphasis><emphasis><literal><vendor></literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal><token></literal></emphasis><emphasis role="bold"><literal>”</literal></emphasis>
|
|
property and must not be included in the
|
|
<emphasis role="bold"><literal>“rtas-sensors”</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>“ibm,get-sensor-indices-types”</literal></emphasis> property,
|
|
users of data in the
|
|
<emphasis role="bold"><literal>“ibm,environmental-sensors”</literal></emphasis> property for
|
|
that sensor token must not assume that the indices are contiguous for that
|
|
sensor token (that is, any of the indices between 0 and the maxindex,
|
|
inclusive, may be missing).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="dbdoclet.50569332_80480">
|
|
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
|
|
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
|
|
<listitem>
|
|
<para>When the value of
|
|
any index returned is 0xFFFFFFFF, the OS must use the
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> and
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS functions for this
|
|
sensor or indicator, using the location code to identify the sensor or
|
|
indicator.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
|
|
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
|
|
<listitem>
|
|
<para>The OS must not call
|
|
<emphasis>get-sensor-state</emphasis> or
|
|
<emphasis>get-indicator</emphasis> with an index value of 0xFFFFFFFF.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<section xml:id="dbdoclet.50569332_30542">
|
|
<title><emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call behaves as the RTAS
|
|
<emphasis>set-indicator</emphasis> call, except that the instance of the
|
|
indicator is identified by a location code instead of a index.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry xml:id="dbdoclet.50569332_58519">
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para>Platforms that
|
|
implement any indicators that are identified by location code instead of
|
|
index (see Requirement
|
|
<xref linkend="dbdoclet.50569332_80480" />) must implement the
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS function.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para>The RTAS function
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> must implement the argument
|
|
call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_14870" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14870">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">
|
|
<emphasis>Name</emphasis>
|
|
</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="5">
|
|
<para>In</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Token</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token for
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Inputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>3</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Outputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>1</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Indicator</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token defining the indicator</para>
|
|
<para>9006: Error Log</para>
|
|
<para>9007: Identify Indicator</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>State</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Desired new state; see
|
|
<xref linkend="dbdoclet.50569332_32237" />.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Location Code Address</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Real or Logical address of a location code string, in the
|
|
format defined by Requirement
|
|
<xref linkend="dbdoclet.50569332_69341" /></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Out</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Status</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>-1: Hardware error</para>
|
|
<para>-2: Busy, try again later</para>
|
|
<para>-3: No such indicator</para>
|
|
<para>0: Success</para>
|
|
<para>990x: Extended delay, where x is a number between 0 and
|
|
5, as described below</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>When 990x
|
|
<emphasis>Status</emphasis> is returned, it is suggested that software
|
|
delay for 10 raised to the power
|
|
<emphasis>x</emphasis> milliseconds (where
|
|
<emphasis>x</emphasis> is the last digit of the 990x return code), before
|
|
calling
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> with the same indicator
|
|
type and location code. However, software may call
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> again either earlier or
|
|
later than this.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
|
|
<listitem>
|
|
<para>The OS must not call
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> with a different indicator
|
|
until a non-busy return
|
|
<emphasis>Status</emphasis> has been received from the previous
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>The location code string referenced by the
|
|
<emphasis>Location Code Address</emphasis> argument in the
|
|
<emphasis>ibm,set-dynamic-indicator</emphasis> argument call buffer must
|
|
reside in contiguous in real memory below an address of 4GB.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="dbdoclet.50569332_69341">
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
|
|
<listitem>
|
|
<para>The input data
|
|
format in the work area must be as follows:</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>32-bit integer length of the location code string, including
|
|
NULL</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Location code string, NULL terminated, identifying the sensor to
|
|
be set.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
|
|
<listitem>
|
|
<para>The platform must not modify the location
|
|
code string.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
|
|
<listitem>
|
|
<para>The OS must only use this call for
|
|
indicators which have been provided by the
|
|
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
|
|
0xFFFFFFFF.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
|
|
<listitem>
|
|
<para>Platforms must identify all indicators
|
|
except types 9006 and 9007 by index.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
|
|
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
|
|
<listitem>
|
|
<para>The <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS call must return A
|
|
<emphasis>Status</emphasis> of -3 for the following conditions:</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>Indicator type not supported</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The specified location code does not identify a valid
|
|
indicator</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_61055">
|
|
<title><emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call</title>
|
|
<para>This RTAS call behaves as the RTAS
|
|
<emphasis>get-sensor-state</emphasis> call, except that the instance of
|
|
the sensor is identified by a location code instead of a index.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry xml:id="dbdoclet.50569332_54151">
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para>Platforms that
|
|
implement any sensors that are identified by location code instead of
|
|
index (see Requirement
|
|
<xref linkend="dbdoclet.50569332_80480" />) must implement the
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS function.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para>The RTAS function
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> must implement the
|
|
argument call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_71500" />.</para>
|
|
<para> </para>
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71500">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>In</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Token</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token for
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Inputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>2</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Outputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>2</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Sensor</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token defining the sensor</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para> </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> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>State</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Current state of the sensor as defined in the
|
|
<emphasis>Defined Values</emphasis> column of
|
|
<xref linkend="dbdoclet.50569332_23534" />.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>When 990x
|
|
<emphasis>Status</emphasis> is returned, it is suggested that software
|
|
delay for 10 raised to the power
|
|
<emphasis>x</emphasis> milliseconds (where
|
|
<emphasis>x</emphasis> is the last digit of the 990x return code), before
|
|
calling
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with the same indicator
|
|
type and location code. However, software may call
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> again either earlier or
|
|
later than this.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
|
|
<listitem>
|
|
<para>The OS must not call
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with a different sensor
|
|
until a non-busy return
|
|
<emphasis>Status</emphasis> has been received from the previous
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>The work area must be contiguous in real
|
|
memory and must reside below 4GB.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="dbdoclet.50569332_75857">
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
|
|
<listitem>
|
|
<para>The input data
|
|
format in the work area must be as follows:</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>32-bit integer length of the location code string, including
|
|
NULL</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Location code string, NULL terminated, identifying the sensor to
|
|
be set.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
|
|
<listitem>
|
|
<para>The platform must not modify the location
|
|
code string.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
|
|
<listitem>
|
|
<para>The OS must only use this call with sensors
|
|
which have been provided by the
|
|
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
|
|
0xFFFFFFFF.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
|
|
<listitem>
|
|
<para>The platform must use the
|
|
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS call only for
|
|
dynamic sensor types of 9004, 9006 and 9007.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
|
|
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
|
|
<listitem>
|
|
<para>A <emphasis>Status</emphasis> of -3 must be returned for the following
|
|
conditions:</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>Sensor type not supported</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The specified location code does not identify a valid
|
|
sensor</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_72964">
|
|
<title><emphasis>ibm,get-vpd</emphasis> RTAS Call</title>
|
|
<para>This RTAS call allows for collection of VPD that changes after OS
|
|
boot time (after the initial reporting in the OF device tree). When this
|
|
call is implemented, there is no overlap between what is reported in the
|
|
device tree and what is reported with this RTAS call. Also, when this
|
|
RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
|
|
is dynamically changed during OS run time is reported with this call and
|
|
not via the
|
|
<emphasis role="bold"><literal>“ibm,vpd”</literal></emphasis> property in the OF device
|
|
tree.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para>For all Dynamic Reconfiguration options
|
|
except PCI Hot Plug, when the platform VPD can change dynamically due to
|
|
a Dynamic Reconfiguration operation, the platform must implement the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para>The RTAS function
|
|
<emphasis>ibm,get-vpd</emphasis> must implement the argument call buffer
|
|
defined by
|
|
<xref linkend="dbdoclet.50569332_62393" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62393">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,get-vpd</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="6">
|
|
<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 “B” starts a new
|
|
<emphasis>ibm,get-vpd</emphasis> sequence while processor “A”
|
|
has a call sequence in process (that is, the function on processor
|
|
“A” has returned a
|
|
<emphasis>Status</emphasis> of 1, and the subsequent call has not yet been
|
|
made) then the call sequence on processor “A” 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>“ibm,vpd”</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>“ibm,vpd”</literal></emphasis> or
|
|
<emphasis role="bold"><literal>“ibm,loc-code”</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>“ibm,vpd-size”</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>“ibm,vpd-size”</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’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>“reg”</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>“reg”</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>“ibm,preservable”</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>“ibm,preservable”</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>“ibm,preservable”</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>“ibm,preserved”</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>“ibm,preserved-storage”</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>“ibm,request-partition-shutdown”</literal></emphasis> property
|
|
which reflects the value of the partition shutdown configuration
|
|
variable, and if this property is not present, a value of 0 must be
|
|
assumed by the OS.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_26596">
|
|
<title><emphasis>ibm,lpar-perftools</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call provides access to platform-level facilities for
|
|
performance tools running in a partition on an LPAR system. Platforms may
|
|
require platform-specific tools, beyond the scope of this architecture,
|
|
to make this call available.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> The platform
|
|
must implement the LPAR option.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> RTAS must
|
|
implement the
|
|
<emphasis>ibm,lpar-perftools</emphasis> call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_48993" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_48993">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,lpar-perftools</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="7">
|
|
<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">
|
|
<title><emphasis>ibm,suspend-me</emphasis> RTAS Call</title>
|
|
<para>The
|
|
<emphasis>ibm,suspend-me</emphasis> RTAS call provides the calling OS the
|
|
ability to suspend processing. Suspension of processing is required as
|
|
part of OS hibernation or migration to another platform. This RTAS call
|
|
is made by the last active processor thread of a partition. The OS uses
|
|
the H_JOIN hcall() (see
|
|
<xref linkend="LoPAR.Virtualization" />) to deactivate other
|
|
processing threads. Processing treads may exit H_JOIN due to an
|
|
unmaskable interrupt; if a thread has exited H_JOIN,
|
|
<emphasis>ibm,suspend-me</emphasis> fails with a status of “multiple
|
|
processor threads active”. The wake up from suspension is triggered
|
|
by partition state change (see
|
|
<xref linkend="LoPAR.Virtualization" /> sections on "Partition Migration"
|
|
and "Partition Hibernation"). The
|
|
<emphasis>ibm,suspend-me</emphasis> RTAS call returns only on the calling
|
|
virtual processor. Other virtual processors that were inactive when
|
|
<emphasis>ibm,suspend-me</emphasis> was called remain so until they are
|
|
proded by the OS.</para>
|
|
<para>While the logical configuration of a suspended partition remains
|
|
static, the physical properties may change; the OS may wish to issue
|
|
<emphasis>ibm,update-nodes</emphasis> (see
|
|
<emphasis>
|
|
<xref linkend="dbdoclet.50569332_84414" />) to determine if any device
|
|
tree nodes changed, and then</emphasis> refresh its view of the device
|
|
tree physical properties using
|
|
<emphasis>ibm,update-properties</emphasis> (see
|
|
<xref linkend="dbdoclet.50569332_40069" />) and/or
|
|
<emphasis>ibm,configure-connector</emphasis> (see
|
|
<xref linkend="LoPAR.Virtualization" />). Also during suspension, some
|
|
system parameters may have changed. See
|
|
<xref linkend="dbdoclet.50569332_10519" />, for details. The OS may want
|
|
to re-scan selected system parameters.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
|
|
must implement the Logical Partitioning option (see
|
|
<xref linkend="LoPAR.Virtualization" />)
|
|
<emphasis>.</emphasis></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> RTAS must
|
|
implement the
|
|
<emphasis>ibm,suspend-me</emphasis> call within a logical partition using
|
|
the argument call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_91600" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_91600">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,suspend-me</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="2">
|
|
<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> </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 “suspendable state”, else return
|
|
a status of -9004 “Partition not suspendable”.</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 “Multiple processor threads active”.</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 “update OF tree” 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 “Partner partition suspended” 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 “Partner partition suspended” 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’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>“compatible”</literal></emphasis> property of the
|
|
platform’s
|
|
<emphasis>v-scsi</emphasis> and
|
|
<emphasis>v-scsi-host</emphasis> nodes must include
|
|
<emphasis role="bold"><literal>“IBM,v-scsi-2”</literal></emphasis> and
|
|
<emphasis role="bold"><literal>“IBM,v-scsi-host-2”</literal></emphasis> respectively
|
|
indicating the platform supports the “Partner partition
|
|
suspended” 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 “Outstanding COP Operations”.</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"> </emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>0-15</para>
|
|
</entry>
|
|
<entry>
|
|
<para>HMC</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>18-19</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Legacy processor CoD</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>20</para>
|
|
<para> </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> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>DesiredEntitledCapacity</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>DesiredMemory</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>DesiredNumberOfProcessors</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>DesiredVariableCapacityWeight</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>DispatchWheelRotationPeriod</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </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> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>22</para>
|
|
</entry>
|
|
<entry>
|
|
<para>platform_auto_power_restart</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>23</para>
|
|
</entry>
|
|
<entry>
|
|
<para>sp-remote-pon</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>24</para>
|
|
</entry>
|
|
<entry>
|
|
<para>sp-rb4-pon</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>25</para>
|
|
</entry>
|
|
<entry>
|
|
<para>sp-snoop-str</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>30</para>
|
|
</entry>
|
|
<entry>
|
|
<para>sp-call-home</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>31</para>
|
|
</entry>
|
|
<entry>
|
|
<para>sp-current-flash-image</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>33</para>
|
|
</entry>
|
|
<entry>
|
|
<para>epow3-quiesce-time</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>34</para>
|
|
</entry>
|
|
<entry>
|
|
<para>memory-preservation-boot-time</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>35</para>
|
|
</entry>
|
|
<entry>
|
|
<para>SCSI initiator identifier</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>36</para>
|
|
</entry>
|
|
<entry>
|
|
<para>AIX support</para>
|
|
</entry>
|
|
<entry>
|
|
<para>The keyword “support” may not change to the
|
|
value “no” for an AIX client.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>37</para>
|
|
</entry>
|
|
<entry>
|
|
<para>enhanced processor CoD</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>38</para>
|
|
</entry>
|
|
<entry>
|
|
<para>enhanced memory CoD</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>39</para>
|
|
</entry>
|
|
<entry>
|
|
<para>CoD Options</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>41</para>
|
|
</entry>
|
|
<entry>
|
|
<para>firmware boot options</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>43</para>
|
|
</entry>
|
|
<entry>
|
|
<para>processor module information</para>
|
|
</entry>
|
|
<entry>
|
|
<para> </para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_84414">
|
|
<title><emphasis>ibm,update-nodes</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call is used to determine which device tree nodes have
|
|
changed due to a massive platform reconfiguration such as when the
|
|
partition is migrated between machines. Differing platform
|
|
reconfigurations are expected to potentially result in different sets of
|
|
nodes being updated; the “scope” argument communicates what
|
|
set of changes are to be reported. The work area is a 4 KB naturally
|
|
aligned area of storage below the first 4 GB; as such, it may not be
|
|
large enough to contain the reports of all changed nodes. The status
|
|
value of 1 is used to inform the caller that there are more updates to
|
|
report and that it will have to call the
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS again to receive them. On
|
|
subsequent calls the state variable, which is set to zero on the first
|
|
call, is set to the value returned on the previous call, to supply RTAS
|
|
with the information it needs to continue from where the previous call
|
|
ended.</para>
|
|
<para>Upon return, the work area contains, in addition to the state
|
|
variable, zero or more operation lists, and logically ends with a
|
|
terminator (4 byte word naturally aligned containing 0x00000000). An
|
|
operation list consists of an operator (4 bytes naturally aligned) and
|
|
zero or more (up to a the maximum number of 4 byte locations remaining in
|
|
the work area) operands, each 4 bytes long. An operator consists of a
|
|
single byte opcode followed by 3 bytes encoded with the binary value of
|
|
the number of operands that follow. An operator with an operand length
|
|
field of zero performs no operation, and the opcode of zero is reserved
|
|
for the terminator -- thus the terminator can be considered a special
|
|
encoding of a no-op operator.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The opcode of 0x01 is used for deleted nodes -- the operands are
|
|
the
|
|
<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The opcode of 0x02 is used for updated nodes -- the operands are
|
|
the
|
|
<emphasis role="bold">phandle</emphasis> values for the updated nodes. The updated
|
|
properties are obtained using the
|
|
<emphasis>ibm,update-properties</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The opcode of 0x03 is used for adding nodes -- the operands are
|
|
pairs of
|
|
<emphasis role="bold">phandle</emphasis> and
|
|
<emphasis role="bold">drc-index</emphasis> values; the
|
|
<emphasis role="bold">phandle</emphasis> value denotes the parent node of the node to
|
|
be added and the
|
|
<emphasis role="bold">ibm,drc-index</emphasis> value is passed with the
|
|
<emphasis>ibm,configure-connector</emphasis> RTAS call to obtain the
|
|
contents of the added node.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>To make processing of device tree updates simpler, all opcode 0x01
|
|
(delete) operations (if any) are presented prior to all opcode 0x02
|
|
(update) operations (if any), and finally any 0x03 (addition) operations
|
|
are presented. The
|
|
<emphasis role="bold">phandle</emphasis> operand values are the same
|
|
<emphasis role="bold">phandle</emphasis> values as reported by the
|
|
<emphasis role="bold"><literal>“ibm,phandle”</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>“ibm,phandle”</literal></emphasis> property in all OF nodes
|
|
specified in
|
|
<xref linkend="dbdoclet.50569332_80965" />.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
|
|
implement the
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_55185" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55185">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,update-nodes</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="4">
|
|
<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 “Parameter Error”.</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 “
|
|
<emphasis>Scope</emphasis>” must be formatted as specified in
|
|
<xref linkend="dbdoclet.50569332_76526" />, else RTAS may return -3
|
|
“Parameter Error”.</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’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
|
|
|
|
<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
|
|
<listitem>
|
|
<para>The opcode of 0x02 in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
|
|
used to denote updated nodes.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
|
|
<listitem>
|
|
<para>The operands for opcode 0x02 in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the
|
|
<emphasis role="bold">phandle</emphasis> values for the updated nodes that may be used
|
|
as the
|
|
<emphasis>ibm,update-properties</emphasis> RTAS call argument to obtain
|
|
the changed properties of the updated node.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
|
|
<listitem>
|
|
<para>The opcode of 0x03 in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must used
|
|
for the added nodes.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
|
|
<listitem>
|
|
<para>The operands for opcode of 0x03 in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
|
|
<emphasis role="bold">phandle</emphasis> and
|
|
<emphasis role="bold">drc-index</emphasis> value pairs (each value being 4 bytes
|
|
on a natural boundary totalling 8 bytes for the pair) denoting the parent
|
|
node of the added node and the
|
|
<emphasis>ibm,configure-connector</emphasis> RTAS call argument to obtain
|
|
the contents of the added node respectively.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
|
|
<listitem>
|
|
<para>All opcode 0x01 (delete) in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
|
|
must be presented prior to any opcode 0x02 (update) operations (if
|
|
any).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
|
|
<listitem>
|
|
<para>All opcode 0x02 (update) in an
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
|
|
must be presented prior to any opcode 0x03 (add) operations (if
|
|
any).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
|
|
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
|
|
<listitem>
|
|
<para>The work area on subsequent call(s) to
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS for the same value of the
|
|
<emphasis role="bold"><literal>“Scope”</literal></emphasis> must be formatted as specified in
|
|
<xref linkend="dbdoclet.50569332_64422" />, else RTAS may return -3
|
|
“Parameter Error”.</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’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 “<emphasis>Scope</emphasis>” 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
|
|
“Parameter Error”.</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>“Scope”</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 “
|
|
<emphasis>Scope</emphasis>” 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>“name”</literal></emphasis> or
|
|
<emphasis role="bold"><literal>“device_type”</literal></emphasis> property)</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Supported Opcodes</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="7">
|
|
<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>
|
|
<entry>
|
|
<para>
|
|
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>0x01-0x03</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="13">
|
|
<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><all></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>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>0x01-0x03</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>2 Activate Firmware</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>rtas</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>0x02</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_40069">
|
|
<title><emphasis>ibm,update-properties</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call is used to report updates to the properties changed
|
|
due to a massive platform reconfiguration such as when the partition is
|
|
migrated between machines. This RTAS call reports changes in the node
|
|
specified by the phandle value in the work area passed using the Work
|
|
Area Address argument. The phandle value may be that of a critical node
|
|
that the caller is interested in or one reported by
|
|
<emphasis>ibm,update-nodes</emphasis> RTAS call. These changes may include
|
|
any combination of new values, deleted and added properties. Updates for
|
|
a given node are retained until the platform is subsequently
|
|
reconfigured, and remain available to subsequent calls to
|
|
<emphasis>ibm,update-nodes</emphasis>.</para>
|
|
<para>There may be more changes than can be reported in a single 4 K work
|
|
area. In this case, the RTAS call returns with a status of 1 “More
|
|
properties updated -- call again”. On the first call, the second
|
|
word of the work area contains the value 0 specifying that the RTAS call
|
|
is to start with the first changed property for the specified updated
|
|
node. On a call with a status value of 1, the first sixteen (16) bytes of
|
|
the work area contain values that, when subsequently supplied in the work
|
|
area of another call to
|
|
<emphasis>ibm,update-properties</emphasis> RTAS, specify that the call
|
|
returns the updated property data for properties after those reported in
|
|
the previous call.</para>
|
|
<para>A single updated property value string may exceed the capacity of a
|
|
single 4 K work area. In that case, the updated property value descriptor
|
|
for the property appears in the work area of multiple sequential calls to
|
|
<emphasis>ibm,update-properties</emphasis> RTAS. When the updated property
|
|
value descriptor contains the final data for the property value, the
|
|
property string length field of the updated property value descriptor is
|
|
a positive number. When the updated property value descriptor contains
|
|
either the initial or interim data for the property value, the updated
|
|
property string length field is a negative number denoting the twos
|
|
complement of the length of the updated property string contained in the
|
|
work area. The data value strings for a given property name are
|
|
concatenated until the final updated property value descriptor is
|
|
processed.</para>
|
|
<para>The first value returned, with an updated property name string of
|
|
NULL, is always the node’s name (for example: full path ||
|
|
<emphasis>name</emphasis> property value || @ unit address) even if there
|
|
has been no change.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
|
|
implement the
|
|
<emphasis>ibm,update-properties</emphasis> RTAS call using the argument
|
|
call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_63317" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_63317">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,update-properties</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="4">
|
|
<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 “Parameter Error”.</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
|
|
“Parameter Error”.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_84989">
|
|
<title>Initial Format of Work Area for
|
|
<emphasis>ibm,update-properties</emphasis></title>
|
|
<tgroup cols="1">
|
|
<colspec colname="c1" colwidth="100*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">phandle</emphasis> of updated node containing updated
|
|
properties to be reported (4 bytes)</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>0x00000000 (Indicates Initial call for specified
|
|
<emphasis role="bold">phandle</emphasis>)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>8 bytes of 0x00 (reserved)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Don’t Care . . .</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_40069"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>Upon successful return (non-negative status
|
|
value) from
|
|
<emphasis>ibm,update-properties</emphasis> the work area must by formatted
|
|
as defined in
|
|
<xref linkend="dbdoclet.50569332_72959" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_72959">
|
|
<title>Return Format of Work Area for
|
|
<emphasis>ibm,update-properties</emphasis></title>
|
|
<tgroup cols="2">
|
|
<colspec colname="c1" colwidth="50*" />
|
|
<colspec colname="c2" colwidth="50*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Description</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Comments</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">phandle</emphasis> of updated node containing updated
|
|
properties to be reported.</para>
|
|
</entry>
|
|
<entry>
|
|
<para>4 Bytes</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>State Variable</para>
|
|
<para>(to be returned if status argument value = 1)</para>
|
|
</entry>
|
|
<entry>
|
|
<para>4 Bytes</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Reserved</para>
|
|
</entry>
|
|
<entry>
|
|
<para>8 bytes</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Number of properties reported in the work area</para>
|
|
</entry>
|
|
<entry>
|
|
<para>4 Bytes</para>
|
|
<para>The number (N) of updated property value descriptors that
|
|
follow -- see below</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>N updated property value descriptors</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Each updated property value descriptor is formatted
|
|
as:</para>
|
|
<para> </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> </para>
|
|
<para>0x00000000 Name only property (
|
|
<emphasis role="bold"><literal>“encode-null”</literal></emphasis>) no value
|
|
follows</para>
|
|
<para> </para>
|
|
<para>0x80000000 The property is to be deleted no value
|
|
follows</para>
|
|
<para> </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> </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> </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
|
|
“Parameter Error”.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_96468">
|
|
<title>Format of Work Area for Subsequent Calls to
|
|
<emphasis>ibm,update-properties</emphasis></title>
|
|
<tgroup cols="1">
|
|
<colspec colname="c1" colwidth="100*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">phandle</emphasis> of updated node containing updated
|
|
properties to be reported (4 Bytes)</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>Value from last call to
|
|
<emphasis>ibm,update-properties</emphasis> RTAS that returned
|
|
status of 1 (12 bytes).</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Don’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>“Scope”</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 “Scope” 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 “
|
|
<emphasis>Scope</emphasis>”</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>“name”</literal></emphasis> or
|
|
<emphasis role="bold"><literal>“device_type”</literal></emphasis> property)</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Property Name</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="6">
|
|
<para>All negative values: Resource Reassignment events as from
|
|
event-scan RTAS</para>
|
|
</entry>
|
|
<entry>
|
|
<para>/memory</para>
|
|
</entry>
|
|
<entry>
|
|
<para><emphasis role="bold"><literal>“ibm,associativity”</literal></emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>ibm,dynamic-reconfiguration-memory</para>
|
|
</entry>
|
|
<entry>
|
|
<para><emphasis role="bold"><literal>“ibm,dynamic-memory”</literal></emphasis></para>
|
|
<para><emphasis role="bold"><literal>“ibm,dynamic-memory-v2”</literal></emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>cpu</para>
|
|
</entry>
|
|
<entry>
|
|
<para>“ibm,associativity”</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="31">
|
|
<para>1 Partition Migration / Hibernation</para>
|
|
</entry>
|
|
<entry morerows="18">
|
|
<para>
|
|
<emphasis role="bold"><literal>root</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,model-class”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“clock-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,extended-clock-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“model”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“compatible”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“name”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“system-id”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,partition-no”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-info”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-indexes”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-names”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-power-domains”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-types”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,aix-diagnostics”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,diagnostic-lic”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,platform-hardware-notification”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,ignore-hp-po-fails-for-dlpar”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,managed-address-types”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,service-indicator-mode”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>openprom</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“model”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="8">
|
|
<para>
|
|
<emphasis role="bold"><literal>rtas</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“power-on-max-latency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,associativity-reference-points”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,max-associativity-domains”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,configure-kernel-dump”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,configure-kernel-dump-sizes”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,configure-kernel-dump-version”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,read-slot-reset-state-functions”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,configure-pe”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,change-msix-capable”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="1">
|
|
<para>
|
|
<emphasis role="bold"><literal>vdevice</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-names”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,drc-info”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>children of the
|
|
<emphasis role="bold"><literal>vdevice</literal></emphasis> node</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,loc-code”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="31">
|
|
<para>1 Partition Migration / Hibernation</para>
|
|
<para> </para>
|
|
</entry>
|
|
<entry morerows="20">
|
|
<para>
|
|
<emphasis role="bold"><literal>cpu</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“name”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“d-cache-sets”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“d-cache-size”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“i-cache-sets”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“i-cache-size”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“bus-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,extended-bus-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>
|
|
“ibm,extended-clock-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“clock-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“timebase-frequency”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“l2-cache”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“performance-monitor”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,associativity”</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>“slb-size”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,tbu40-offset”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,pi-features”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,spurr”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,pa-optimizations”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,dfp”</literal></emphasis> (sign bit
|
|
only)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,sub-processors”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="4">
|
|
<para>
|
|
<emphasis role="bold"><literal>cache</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“d-cache-sets”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“d-cache-size”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“i-cache-sets”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“i-cache-size”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>l2-cache</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>options</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,dasd-spin-interval”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>memory</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,associativity”</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="2">
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,dynamic-reconfiguration-memory</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><emphasis role="bold"><literal>“ibm,associativity-lookup-arrays”</literal></emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><emphasis role="bold"><literal>“ibm,dynamic-memory”</literal></emphasis></para>
|
|
<para><emphasis role="bold"><literal>“ibm,dynamic-memory-v2”</literal></emphasis></para>
|
|
<para>only the associativity list index fields</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><emphasis role="bold"><literal>“ibm,memory-preservation-time”</literal></emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>/chosen</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,architecture-vec-5”</literal></emphasis>
|
|
</para>
|
|
<para>byte 3 (I/O Super Page Option support parameters)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="3">
|
|
<para>1 Partition Migration / Hibernation</para>
|
|
<para> </para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,random-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,encryption-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>ibm,memory-utilization_instrumentation-v#</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para><all></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>2 Activate Firmware</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold"><literal>rtas</literal></emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Any
|
|
<emphasis role="bold"><literal>/rtas</literal></emphasis> node property as defined per LoPAR
|
|
remains invariant.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any
|
|
<emphasis role="bold"><literal>/rtas</literal></emphasis> node property or definition
|
|
extension, except for the value of a function token property*,
|
|
may change (provided that the client program has indicated
|
|
support for such property or definition extension) including
|
|
the following:</para>
|
|
<para>
|
|
<emphasis role="bold"><literal>“ibm,read-slot-reset-state-functions”
|
|
“ibm,configure-pe”</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">
|
|
<title><emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call is used to register and unregister with the platform
|
|
a data structure describing kernel dump information. This dump
|
|
information is preserved as needed by the platform in support of a
|
|
platform assisted kernel dump option.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
option:</emphasis> The platform must implement the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call using the
|
|
argument call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_24141" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24141">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,configure-kernel-dump</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter Type</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Name</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Values</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="5">
|
|
<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,
|
|
“Parameter Error.”</para>
|
|
<para>The Dump Memory Structure specified in
|
|
<xref linkend="dbdoclet.50569332_76933" /> is passed by the operating
|
|
system during a
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call. It is also
|
|
reported by the platform using the
|
|
<emphasis>ibm,kernel-dump</emphasis> RTAS property after a dump has been
|
|
initiated.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76933">
|
|
<title>Kernel Assisted Dump Memory Structure</title>
|
|
<tgroup cols="5">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="1*" />
|
|
<colspec colname="c3" colwidth="1*" />
|
|
<colspec colname="c4" colwidth="2*" />
|
|
<colspec colname="c5" colwidth="2*" />
|
|
<thead>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Header</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>Offset</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Number of Bytes</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Value</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x0</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Format Version = 0x00000001</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x4</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of Kernel Dump Sections</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x6</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Status Flags</para>
|
|
<para>A bit mask with value</para>
|
|
<para>0x8000 = Dump performed (Set to 0 by caller of the
|
|
ibm,configure-kernel-dump call)</para>
|
|
<para>0x4000 = Dump was triggered by the previous system boot
|
|
(set by platform)</para>
|
|
<para>0x2000 = Dump error occurred (set by platform)</para>
|
|
<para>All other bits reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x8</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Offset to first Kernel Dump Section, offset from the
|
|
beginning of the Structure</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0xc</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of bytes in a block of the dump-disk, if data to
|
|
be written to a dump-disk, If not, should be set to 0
|
|
(indicating the no disk dump option.)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x10</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Starting block# offset on dump-disk (set to 0 for the no
|
|
disk dump option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x18</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of blocks on dump-disk usable for dump (set to 0
|
|
for the no disk dump option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x20</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Offset from start of structure to a Null-terminated
|
|
Dump-disk path string (set to 0 for the no disk dump
|
|
option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x24</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Maximum time allowed (milliseconds) after
|
|
Non-Maskable-Interrupt for the OS to call
|
|
<emphasis>ibm,configure-kernel-dump</emphasis>
|
|
<emphasis>Function</emphasis> 2 (unregister) to prevent an
|
|
automatic dump-reboot (set to 0 to disable the automatic
|
|
dump-reboot function)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Dump-disk Path String</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Offset specified above</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Varies</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Null-terminated Dump-disk path string specifying the
|
|
dump-disk. If no disk dump option is indicated, this section is
|
|
not included.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>First Kernel Dump Section</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Offset specified above</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Request Flags:</para>
|
|
<para>A bit-mask</para>
|
|
<para>Bit 0x00000001 When set, firmware to copy source data to
|
|
partition memory. This option must be selected if no disk dump
|
|
option is indicated.</para>
|
|
<para>All other bit values reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+4</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Source Data type, describes section of dump memory being
|
|
described</para>
|
|
<para>0x0001 = CPU State Data</para>
|
|
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
|
|
<para>0x0011 = Real Mode Region</para>
|
|
<para>0x0012 = Dump OS identified string (identifies that the
|
|
dump is for a particular OS type and version)</para>
|
|
<para>0x0100 - 0xFFFF OS defined source types</para>
|
|
<para>All Other values reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+6</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Error Flags (set by platform)</para>
|
|
<para>Bit mask</para>
|
|
<para>0x8000 = Invalid section data type</para>
|
|
<para>0x4000 = Invalid source address</para>
|
|
<para>0x2000 = Requested section length exceeds source</para>
|
|
<para>0x1000 = Invalid partition destination address</para>
|
|
<para>0x0800 = Partition memory destination too small</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+8</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Source address (logical address if section came from
|
|
partition memory, or byte offset if section is platform
|
|
memory)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+16</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Requested data length, represents number of bytes to
|
|
dump</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+24</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Actual data length, number of bytes dumped</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+32</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Destination address, logical address used for sections
|
|
not written to disk by the platform, always required for a Real
|
|
mode region section and for all sections when the no disk dump
|
|
option is used.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Subsequent Sections</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Previous Section Start+40</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Start of Next Section</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>A total of up to nine additional 40 bytes sections with
|
|
values as described in the First Section may be specified so
|
|
long as the entire structure does not exceed 512 bytes for
|
|
version 1.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis>ibm,os-term</emphasis> RTAS call, or on a system reset without
|
|
an
|
|
<emphasis>ibm,nmi-interlock</emphasis> RTAS call, if the platform has a
|
|
dump structure registered through the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> call, the platform must
|
|
process each registered kernel dump section as required and, when
|
|
available, present the dump structure information to the operating system
|
|
through the
|
|
<emphasis role="bold"><literal>“ibm,kernel-dump”</literal></emphasis> property, updated with
|
|
status for each dump section, until the dump has been invalidated through
|
|
the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
|
|
register or unregister for a dump while a dump is currently active, the
|
|
platform must return a
|
|
<emphasis>Status</emphasis> of -9, “Dump Active” indicating
|
|
that a dump has been copied by the platform and a call must be made to
|
|
complete/invalidate the active dump before another call to register or
|
|
unregister a dump can be completed successfully.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
|
|
<listitem>
|
|
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
|
|
register a dump after a dump has already been registered by a call, the
|
|
platform must return a
|
|
<emphasis>Status</emphasis> of -8, “Dump Already Registered”
|
|
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>“ibm,configure-kernel-dump-sizes”</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>“ibm-configure-kernel-dump-version”</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>“ibm,ddw-applicable”</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>“ibm,dma-window”</literal></emphasis> property. During
|
|
partition migration, these RTAS calls may come and go, but so will the
|
|
<emphasis role="bold"><literal>“ibm,ddw-applicable”</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>“ibm,dma-window”</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>“ibm,ddw-applicable”</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>“ibm,ddw-applicable”</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>“ibm,ddw-applicable”</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>“ibm,ddw-applicable”</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>“ibm,dma-window”</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>“ibm,dma-window”</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>“ibm,dma-window”</literal></emphasis> property in the OF
|
|
Device Tree for the device.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<section xml:id="dbdoclet.50569332_99826">
|
|
<title><emphasis>ibm,query-pe-dma-window</emphasis></title>
|
|
|
|
<para>This RTAS call allows for the discovery of the resources necessary
|
|
to make a successful subsequent call to
|
|
<emphasis>ibm,create-dma-window</emphasis>.</para>
|
|
|
|
<para>If the <emphasis>ibm,query-pe-dma-window</emphasis> RTAS call is made with Number Outputs
|
|
equal to 6, and the <emphasis role="bold"><literal>“ibm,ddw-extensions”</literal></emphasis>
|
|
property does not include list index of 3,
|
|
then the call will return a Status of -3 (Invalid Parameter).</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para>RTAS must implement a
|
|
<emphasis>ibm,query-pe-dma-window</emphasis> call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_53901" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_53901">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,query-pe-dma-window</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="5">
|
|
<para>In</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Token</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token for
|
|
<emphasis>ibm,query-pe-dma-window</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Inputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>3</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Outputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>5 or 6. The value 6 may be used when the ibm,ddw-extensions property
|
|
in the PHB node specified by this call indicates support for a 64-bit value of
|
|
PE TCEs. See <xref linkend="dbdoclet.50569332_25585" />.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Config_addr</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>PE configuration address (Register fields set to
|
|
0)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>PHB_Unit_ID_Hi</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Represents the most-significant 32-bits of the Unit ID of
|
|
the PHB that corresponds to the
|
|
<emphasis>config_addr</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>PHB_Unit_ID_Low</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Represents the least-significant 32-bits of the Unit ID
|
|
of the PHB that corresponds to the
|
|
<emphasis>config_addr</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="5">
|
|
<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>“ibm,dma-window”</literal></emphasis> property for
|
|
the PE) has not been yet removed via the
|
|
<emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call for that
|
|
window, and if the default window is not needed, then removal
|
|
of the default window makes at least one window
|
|
available.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>PE TCEs hi</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Represents the most-significant 32-bits of the largest contiguous
|
|
block of TCEs allocated specifically for (that is, are reserved for) this PE.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>PE TCEs lo</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Represents the least-significant 32-bits of the largest contiguous block
|
|
of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement
|
|
<xref linkend="dbdoclet.50569332_91197" />.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>IO Page Sizes</para>
|
|
</entry>
|
|
<entry>
|
|
<para>I/O Page Size Support. I/O page sizes supported for this
|
|
PE. This is a bit significant field, defined as follows:</para>
|
|
<para>Bits 0 - 23 reserved</para>
|
|
<para>24 = 16 GB page size supported</para>
|
|
<para>25 = 256 MB page size supported</para>
|
|
<para>26 = 128 MB pages supported</para>
|
|
<para>27 = 64 MB page size supported</para>
|
|
<para>28 = 32 MB page size supported</para>
|
|
<para>29 = 16 MB page size supported</para>
|
|
<para>30 = 64 KB page size supported</para>
|
|
<para>31 = 4 KB page size supported</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Migration Capable</para>
|
|
</entry>
|
|
<entry>
|
|
<para>H_MIGRATE_DMA Mask. Mask to indicate for which page sizes
|
|
(as specified in the I/O Page Size Support field), that
|
|
H_MIGRATE_DMA is supported (for this PE). This is a bit
|
|
significant field, with the bits defined to align to the bits
|
|
in the I/O Page Size Support field.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="dbdoclet.50569332_91197">
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_99826"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis>
|
|
TCE resources returned in the
|
|
<emphasis>PE TCEs</emphasis> parameter of the
|
|
<emphasis>ibm,query-dma-window</emphasis> RTAS call must be allocated to
|
|
the PE specified by the PE configuration address specified in the call,
|
|
and must be available to a subsequent
|
|
<emphasis>ibm,create-dma-window</emphasis> RTAS call for that PE.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="dbdoclet.50569332_49009">
|
|
<title><emphasis>ibm,create-pe-dma-window</emphasis></title>
|
|
|
|
<para>This call allows the creation of a new DMA window, given the size
|
|
of the DMA window, I/O page size, and the PE to which it is associated.
|
|
The return from the call includes the LIOBN of the new DMA window, the
|
|
starting I/O address of the DMA window, and size.</para>
|
|
<para>
|
|
<emphasis role="bold">Software Implementation Note:</emphasis> Software is expected to
|
|
not attempt to create a DMA window that is larger than possible, or
|
|
create more DMA windows than is possible, otherwise the
|
|
<emphasis>ibm,create-pe-dma-window</emphasis> will return a
|
|
<emphasis>Status</emphasis> of -3 (Parameter Error). Thus, the OS is
|
|
expected to use the
|
|
<emphasis>ibm,query-pe-dma-window</emphasis> first and not ask to create a
|
|
window that consumes more resources than those that are available to the
|
|
PE.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_49009"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
|
|
implement the
|
|
<emphasis>ibm,create-dma-window</emphasis> call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_26269" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_26269">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,create-pe-dma-window</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="7">
|
|
<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>“ibm,dma-window”</literal></emphasis> property for the PE. All
|
|
created DMA windows will be removed by the platform, and the default DMA
|
|
window restored, on a partition reboot, on a DR isolate operation (see
|
|
Requirement
|
|
<xref linkend="dbdoclet.50569332_79382" /> and
|
|
<xref linkend="dbdoclet.50569332_72212" />), or if the last remaining DMA
|
|
window for the PE is removed and that window is not the default DMA
|
|
window (see Requirements
|
|
<xref linkend="dbdoclet.50569332_40989" /> and
|
|
<xref linkend="dbdoclet.50569332_34916" />). After removal of a DMA
|
|
window, software needs to use the
|
|
<emphasis>ibm,query-pe-dma-window</emphasis> RTAS call to find out what
|
|
resources are available to the PE for subsequent
|
|
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_60545"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option:</emphasis> RTAS must
|
|
implement the
|
|
<emphasis>ibm,remove-dma-window</emphasis> call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_36074" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_36074">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,remove-pe-dma-window</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="3">
|
|
<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>“ibm,dma-window”</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>“ibm,ddw-extensions”</literal></emphasis> property see
|
|
<xref linkend="LoPAR.DeviceTree" /> to those nodes that include the
|
|
<emphasis role="bold"><literal>“ibm,ddw-applicable”</literal></emphasis> property, and
|
|
implementing the functional extensions specified for the architectural
|
|
level in
|
|
<xref linkend="dbdoclet.50569332_25585" />. The
|
|
<emphasis role="bold"><literal>“ibm,ddw-extensions”</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>“ibm,ddw-extensions”</literal></emphasis> list
|
|
index</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Value Definition</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>2.7</para>
|
|
</entry>
|
|
<entry>
|
|
<para>2</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token of the i
|
|
<emphasis>bm,reset-pe-dma-windows</emphasis> RTAS Call</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>2.7</para>
|
|
</entry>
|
|
<entry>
|
|
<para>3</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Value of 1 indicates the OS may invoke RTAS <emphasis>ibm,query-pe-dma-window</emphasis>
|
|
with Number Outputs equal to 6. Other values are reserved.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="sec_ext_to_ddw"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For compatibility with changing extensions to the Dynamic DMA
|
|
Windows (DDW) option:</emphasis> The client program must ignore extensions
|
|
as represented by
|
|
<emphasis role="bold"><literal>“ibm,ddw-extensions”</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>“ibm,dma-window”</literal></emphasis> OF Device Tree property
|
|
in the for the PE.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="sec_reset_pe_dma_windows"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Dynamic DMA Windows (DDW) option starting with
|
|
IBM <citetitle>Power Architecture Platform Requirements (PAPR)</citetitle>
|
|
level 2.7:</emphasis> RTAS must implement the
|
|
<emphasis>ibm,reset-dma-windows</emphasis> call using the argument call
|
|
buffer defined by
|
|
<xref linkend="dbdoclet.50569332_68052" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_68052">
|
|
<title>Argument Call Buffer
|
|
<emphasis>ibm,reset-pe-dma-windows</emphasis></title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="2*" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="5">
|
|
<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>“ibm,dma-window”</literal></emphasis> Tree property
|
|
in the for the PE (same LIOBN, location, and size).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|