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.
455 lines
20 KiB
XML
455 lines
20 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Copyright (c) 2016, 2020 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns: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="dbdoclet.50569342_85040" /> and
|
|
<xref linkend="dbdoclet.50569342_61130" />.</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><emphasis>ibm,get-indices</emphasis> Argument Call Buffer</title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" align="center" />
|
|
<colspec colname="c2" colwidth="2*" align="center" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Parameter Type</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis role="bold">Name</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry align="center">
|
|
<para>
|
|
<emphasis role="bold">Values</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="middle" >
|
|
<row>
|
|
<entry morerows="7" valign="middle">
|
|
<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" valign="middle">
|
|
<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>
|