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.
268 lines
11 KiB
XML
268 lines
11 KiB
XML
5 years ago
|
<?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_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" 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>
|