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.
409 lines
17 KiB
XML
409 lines
17 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="dbdoclet.50569332_72964">
|
|
<title><emphasis>ibm,get-vpd</emphasis> RTAS Call</title>
|
|
<para>This RTAS call allows for collection of VPD that changes after OS
|
|
boot time (after the initial reporting in the OF device tree). When this
|
|
call is implemented, there is no overlap between what is reported in the
|
|
device tree and what is reported with this RTAS call. Also, when this
|
|
RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
|
|
is dynamically changed during OS run time is reported with this call and
|
|
not via the
|
|
<emphasis role="bold"><literal>“ibm,vpd”</literal></emphasis> property in the OF device
|
|
tree.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para>For all Dynamic Reconfiguration options
|
|
except PCI Hot Plug, when the platform VPD can change dynamically due to
|
|
a Dynamic Reconfiguration operation, the platform must implement the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para>The RTAS function
|
|
<emphasis>ibm,get-vpd</emphasis> must implement the argument call buffer
|
|
defined by
|
|
<xref linkend="dbdoclet.50569332_62393" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62393">
|
|
<title><emphasis>ibm,get-vpd</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="6" valign="middle">
|
|
<para>In</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Token</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token for
|
|
<emphasis>ibm,get-vpd</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Inputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>4</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Outputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>3</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Pointer to Location Code</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Real address of NULL-terminated string, contiguous in
|
|
real memory and below 4GB, which is the location code of the
|
|
FRU for which to obtain the VPD. When this parameter references
|
|
a NULL string the VPD for all location codes is
|
|
returned.</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>Sequence Number</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Integer representing the sequence number of the 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="2" valign="middle">
|
|
<para>Out</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Status</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>-1: Hardware error</para>
|
|
<para>-3: Parameter error</para>
|
|
<para>-4: Optional: VPD 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 Sequence Number</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Return this integer as the
|
|
<emphasis>Sequence Number</emphasis> parameter on the next call
|
|
to continue the sequence, or 1 if no more calls are
|
|
required</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Bytes Returned</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Integer representing the number of valid bytes returned
|
|
in the work area.</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-vpd</emphasis> with the same input parameters. However,
|
|
software may issue the
|
|
<emphasis>ibm,get-vpd</emphasis> call again either earlier or later than
|
|
this.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
|
|
<listitem>
|
|
<para>On the first call to
|
|
<emphasis>ibm,get-vpd</emphasis> for a particular VPD gathering operation,
|
|
the caller must provide a
|
|
<emphasis>Sequence Number</emphasis> of 1 (32-bit integer)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>Upon calling
|
|
<emphasis>ibm,get-vpd</emphasis> with a
|
|
<emphasis>Sequence Number</emphasis> of 1, a previously returned
|
|
<emphasis>Next Sequence Number</emphasis> must be discarded. This means
|
|
that multiple calls to
|
|
<emphasis>ibm,get-vpd</emphasis> cannot be interleaved by multiple
|
|
processors, and if processor “B” starts a new
|
|
<emphasis>ibm,get-vpd</emphasis> sequence while processor “A”
|
|
has a call sequence in process (that is, the function on processor
|
|
“A” has returned a
|
|
<emphasis>Status</emphasis> of 1, and the subsequent call has not yet been
|
|
made) then the call sequence on processor “A” is
|
|
abandoned.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
|
|
<listitem>
|
|
<para>Optionally, if firmware detects a change in
|
|
the VPD being requested before the entire VPD is returned, the
|
|
<emphasis>ibm,get-vpd</emphasis> call must return a
|
|
<emphasis>Status</emphasis> of -4 and the caller must start again with a
|
|
Starting Number of 1.</para>
|
|
<para>
|
|
<emphasis role="bold">Implementation Note:</emphasis> The platform should not impede
|
|
forward progress by continuously returning a
|
|
<emphasis>Status</emphasis> of -4.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
|
|
<listitem>
|
|
<para>The return data format in the work area
|
|
must be such that after returning all the data and concatenating all data
|
|
together in the order received, that the data is the same as is obtained
|
|
from the
|
|
<emphasis role="bold"><literal>“ibm,vpd”</literal></emphasis> property of the OF device
|
|
tree.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
|
|
<listitem>
|
|
<para>Each stanza of the returned data must
|
|
include the YL (location code) keyword.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
|
|
<listitem>
|
|
<para>If the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then the
|
|
platform must not provide the
|
|
<emphasis role="bold"><literal>“ibm,vpd”</literal></emphasis> or
|
|
<emphasis role="bold"><literal>“ibm,loc-code”</literal></emphasis> properties in the OF
|
|
device tree
|
|
<emphasis>root</emphasis> node.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
|
|
<listitem>
|
|
<para>If the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then any VPD
|
|
which may change after OS boot must be reported via the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-10.</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-vpd</emphasis> again with the
|
|
<emphasis>Sequence Number</emphasis> parameter set to the
|
|
<emphasis>Next Sequence Number</emphasis> integer from the previously
|
|
returned call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
|
|
<listitem>
|
|
<para>If a
|
|
<emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
|
|
contents of the work area is not defined.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
|
|
<listitem>
|
|
<para>The work area must be contiguous in real
|
|
memory and must reside below 4GB.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
|
|
<listitem>
|
|
<para>Firmware cannot count on the contents of
|
|
the work area at the beginning of any call to
|
|
<emphasis>ibm,get-vpd</emphasis> (regardless of the value of the
|
|
<emphasis>Sequence Number</emphasis>).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
|
|
<listitem>
|
|
<para>The location code referenced by the
|
|
<emphasis>Pointer to Location Code</emphasis> parameter must reside in
|
|
contiguous real memory below an address of 4GB.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
|
|
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
|
|
<listitem>
|
|
<para>If the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then firmware
|
|
must supply the
|
|
<emphasis role="bold"><literal>“ibm,vpd-size”</literal></emphasis> property in the
|
|
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, the value of which is a single cell,
|
|
encoded as with
|
|
<emphasis>encode-int</emphasis>, which is the estimated maximum size in
|
|
bytes of the VPD that is returned if the
|
|
<emphasis>Pointer to Location Code</emphasis> parameter to the
|
|
<emphasis>ibm,get-vpd</emphasis> RTAS function is NULL (that is, all
|
|
system VPD). This size should take in to account possible concurrent
|
|
addition of new platform elements after the partition is started. If
|
|
firmware is unable to estimate this size, it may return a value of 0x0 to
|
|
indicate that no estimate is available.</para>
|
|
<para>
|
|
<emphasis role="bold">Software Implementation Notes:</emphasis>
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>An OS should be prepared for older versions of firmware where
|
|
the
|
|
<emphasis role="bold"><literal>“ibm,vpd-size”</literal></emphasis> property is not
|
|
provided.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Each stanza of the returned data must include the YL (location
|
|
code) keyword.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|