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.
Linux-Architecture-Reference/LoPAR/sec_rtas_set_dynamic_indica...

279 lines
11 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="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" valign="middle">
<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>