Linux-Architecture-Reference/LoPAR/sec_rtas_lpar_perftools.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_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><emphasis>ibm,lpar-perftools</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,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" valign="middle">
                      <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>