Linux-Architecture-Reference/LoPAR/sec_rtas_set_dynamic_indicator.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="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><emphasis>ibm,set-dynamic-indicator</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">
                          <emphasis>Name</emphasis>
                        </emphasis>
                      </para>
                    </entry>
                    <entry align="center">
                      <para>
                        <emphasis role="bold">Values</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle" >
                  <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>