Add Coherent Platform Facilities (CAPI)

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
pull/1/head
Jeff Scheel 5 years ago
parent b52aecac38
commit 1ff4ccb0f6

@ -562,7 +562,7 @@
<para>If the boot sequence is interrupted by the multiboot key sequence, <para>If the boot sequence is interrupted by the multiboot key sequence,
then the firmware shall present a then the firmware shall present a
<emphasis>multiboot menu</emphasis> that provides at least the functions <emphasis>multiboot menu</emphasis> that provides at least the functions
listed below. The form of the menu (e.g. graphical or text- oriented) and listed below. The form of the menu (e.g. graphical or text-oriented) and
the selection mechanism (e.g. numbered choices, arrow keys, or mouse) are the selection mechanism (e.g. numbered choices, arrow keys, or mouse) are
platform-dependent.</para> platform-dependent.</para>
<para>Multiboot Required Functions:</para> <para>Multiboot Required Functions:</para>
@ -1259,6 +1259,22 @@
<para>Logical Port</para> <para>Logical Port</para>
</entry> </entry>
</row> </row>
<row>
<entry>
<para>COPLATFAC</para>
</entry>
<entry>
<para>Coherent Platform Facility</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFUN</para>
</entry>
<entry>
<para>Coherent Platform Function</para>
</entry>
</row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
@ -4666,7 +4682,7 @@
followed by N integers encoded as with followed by N integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> <emphasis role="bold"><literal>encode-int</literal></emphasis>
each representing each representing
current number of unique asso- ciativity domains the platform supports at that level.</para> current number of unique associativity domains the platform supports at that level.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>


@ -8812,6 +8828,947 @@


</section> </section>


<section xml:id="sec_ibm_coherent_platform_facility_node">
<title><literal>/ibm,coherent-platform-facility node</literal></title>

<para>The <emphasis role="bold">ibm,coherent-platform-facility</emphasis> nodes
represent the coherent platform facilities. Standard property names associated
with the <emphasis role="bold">ibm,coherent-platform-facility</emphasis> node
have special values as specified below.
</para>

<para>Three-cell addresses encoded with encode-phys shall be formatted as follows:
<programlisting><![CDATA[Bit# 33222222 22221111 11111100 00000000
10987654 32109876 54321098 76543210
phys.hicell: 00000000 00000000 00000000 tttttttt
phys.midcell: hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh
phys.locell: llllllll llllllll llllllll llllllll

where:
t = is the type of address, enumerated as:
0x00 = Unit Addressing
0x01 = PSL Privilege 2 Area Address
0x02 = AFU Problem State Area Address
0x03 = Memory Mapped Address
hh..hh = is a 32-bit unsigned number
ll..ll = is a 32-bit unsigned number]]></programlisting>
</para>

<para>When the hh...hh and ll...ll fields are concatenated to form a larger
number, hh...hh is the most significant portion and ll...ll is the least
significant portion.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of cells required to represent a childs
bus address. The value of
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
for the child's bus address shall be 3.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of size cells required to represent a childs
bus address. Shall have the value of 2 indicating that a child node may
take physical address space.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
specifying the programming models that are compatible with this coherent
platform facility. The last value of this property shall be
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-facility&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define the name of the package. This property is encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>
and the value shall be:
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-facility&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define a manufacturers model number. This value defines the programming
version of the facility and has the value of the coherent platform
facility PSL version.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the coherent platform
facility handle.</para>

<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.

<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> and
<emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>

The first value of the property shall be the handle for use with
the coherent platform facility, where
<emphasis>phys-addr</emphasis>
denotes the unit-address. It shall have a size value of 0. This
value is always present.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the mapping of the parent
address space to child address spaces.</para>

<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>child-phys, parent-phys,size</emphasis>) specifications.</para>

<itemizedlist mark="none">
<listitem>
<para><emphasis>child-phys</emphasis> is an addresss, encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
is the child address and shall have a type field indicating Memory Mapped
Address.</para>
</listitem>
<listitem>
<para><emphasis>parent-phys</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> and
is the parent address.</para>
</listitem>
<listitem>
<para><emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></term>
<listitem>
<para>Property name Property name specifying the unique and persistent
location code associated with this coherent platform facility p
resented as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in Ux-Px-Cx.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> specifying the
interrupt-source number(s) and range(s) associated with this coherent
platform facility. The property is presented as an encoded array of
two cells per entry, each cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
with the first cell of an entry containing the first interrupt source
number (ISN <subscript>1</subscript>) of a range and the second cell of an entry containing
an unsigned integer, specifying the count (N) of ISNs in the range,
such that ISN1<subscript>1</subscript>+(N-1) specifies the value of the last
ISN<subscript>N</subscript> in the range.</para>

<para>The interrupt source numbers are assigned and utilized by the children of this node,
<emphasis role="bold"><literal>ibm,coherent-platform-function</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. For the coherent platform facility, the device type the value shall
be the string <emphasis role="bold"><literal>&#8220;capi&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Optionally the
<emphasis role="bold"><literal>/ibm,coherent-platform-facility</literal></emphasis>
node may contain the following properties.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index (value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property) for the
connector between the node and the node&#8217;s parent. The presence of
this indicates that the resource is dynamically reconfigurable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index to be used to
communicate to the firmware what connector is to be operated upon for the
various RTAS calls used for DR.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> describes the external labeling of the
DR connectors.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>

<para>The values shall be the location code for each child node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>, describes the type of each connector
associated with the node, in a human-readable form.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
specifying the number of items in the following list, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> gives the power domain number for each
connector associated with the node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
specifying the number of items in the following list, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>A value other than -1 indicates that the coherent platform facility
power is controlled by the
<emphasis>set-power-level</emphasis> RTAS call. A value of -1 indicates that no
<emphasis>set-power-level</emphasis> RTAS call is required.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis></term>
<listitem>
<para>Package handle for the <emphasis>coherent-platform-facility</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,cai-version&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that describes the CAIA version of the coherent platform facility.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,psl-revision&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that describes the PSL revision of the coherent platform facility.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
or the VPD for the <emphasis>ibm,coherent-platform-facility</emphasis>.
This value is used to size the buffer in H_CONTROL_CA_FACILITY with
operation Collect VPD.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to indicate the operational status
of this device.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>If this property is present, the value is a string indicated the
status of the device, as follows:</para>
<variablelist>
<varlistentry>
<term>"okay"</term>
<listitem>
<para>The device is believed to be operational.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"disabled"</term>
<listitem>
<para>The device represented by this node is not operation, but it
might become operational in the future (e.g., an external switch
is turned off, or something isnt plugged in.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"fail"</term>
<listitem>
<para>The device represented by this node is not operational
because a fault has been detected, and it is unlikely that the
device will become operational without repair. No additional
failure details are available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"fail-xxx"</term>
<listitem>
<para>The device represented by this node is not operational
because a fault has been detected, and it is unlikely that
the device will become operational without repair. “xxx” is
additional human-readable information about the particular
fault condition that was detected.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The absence of this property means that the operational status is
unknown or okay.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,privileged-facility&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies if the <emphasis>ibm,coherent-platform-facility</emphasis>
is privileged. The absence of this property or a property of 0
indicates the facility is not privileged.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis></term>
<listitem>
<para>Device ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis></term>
<listitem>
<para>Revision ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis></term>
<listitem>
<para>Class Code from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
</variablelist>

<section xml:id="sec_children_of_the_ibm_coherent_platform_facility_node">
<title>Children of the /ibm,coherent-platform-facility node</title>

<para>The
<emphasis role="bold">ibm,coherent-platform-function</emphasis>
nodes are the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node represent the individual platform facility functions. Standard property
names associated with the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node have special values as specified below. Note the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node shall contain the following standard properties with their standard
definitions:</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
specifying the programming models that are compatible with this coherent
platform function. A value may be present such as “capiVVVV,DDDD.SSSS.ssss”,
where VVVV is “vendor-id”, DDDD is “device-id”, SSSS is “subsystem-vendor-id”
and ssss is “subsystem-id”. The last value of this property shall be
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define the name of the package. This property is encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>
and the value shall be:
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the coherent platform
function device handle and mmio address regions.</para>

<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.

<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>,
indicating an address relative to value of the associated
<emphasis>assigned-address</emphasis> value.</para>
</listitem>
<listitem>
<para><emphasis>Size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>

The first value of the property shall be the handle for use in
hypervisor calls to the coherent platform function. It shall have a
type of Unit Address and size value of 0. This value is always present.</para>

<para>Optionally additional values may be present that specify if
the coherent-platform-function has access to PSL Privilege 2 Area
or AFU Problem State Area indicated by the type field in the
<emphasis>phys-addr</emphasis>.</para>

<para>To calculate the address of memory-mapped area the
<emphasis>assigned-address phys.mid,phys.lo</emphasis>
field is added to the reg
<emphasis>phys.mid,phys.lo</emphasis> field for the matching area
to give the calculated address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;assigned-addresses&#8221;</literal></emphasis></term>
<listitem>
<para>Property name that defines the coherent platform
function assigned mmio address regions.</para>

<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.

<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>
and denotes the assigned addresses for each register set.</para>
</listitem>
<listitem>
<para><emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></term>
<listitem>
<para>Property name specifying the unique and persistent location
code associated with this coherent platform function presented
as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in Ux-Px-Cx-Sy-Sz,
where y is a logical platform function unit number and z is the
virtual function unit number.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>Optionally a child node of the
<emphasis role="bold"><literal>/ibm,coherent-platform-facility</literal></emphasis>
node with the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> of
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>
may contain as appropriate the following unique properties:</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. For the coherent platform device type the value shall
be the string <emphasis role="bold"><literal>&#8220;ibm,coherent-accel&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index (value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property) for the
connector between the node and the node&#8217;s parent. The presence of
this indicates that the resource is dynamically reconfigurable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#processes&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
defines the number of operating system processes that can be concurrently
attached to the coherent accelerator function via the H_ATTACH_CA_PROCESS
hcall.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,scratchpad-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the size of the
scratch pad area supported by the coherent platform function in terms
of cells. The absence of this parameter or a value of 0 indicates the
coherent platform function does not support a scratch pad area.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programmable&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies if the coherent platform function can be programmed
(via H_DOWNLOAD_CA_FUNCTION) with a value of 1. The absence of this
parameter or a value of 0 indicates the coherent platform function
does not support programming.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis></term>
<listitem>
<para>Package handle for the <emphasis>coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-ints-per-process&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the maximum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that can be assigned per process with the H_ATTACH_CA_PROCESS hcall.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,min-ints-per-process&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the minimum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that must be assigned per process with the H_ATTACH_CA_PROCESS hcall.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-ints&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the maximum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that can be assigned for all processes attached on the
<emphasis>coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
for the VPD for the <emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to size the buffer in H_CONTROL_CA_FUNCTION with
operation Collect VPD.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,error-buffer-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the error buffer size
for the <emphasis>ibm,coherent-platform-function</emphasis>. This
value is used in H_CONTROL_CA_FUNCTION with operation Get Error Buffer.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,config-record-type&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the type of the configuration record for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to identify the format of the Function Configuration
Record and is defined by the CAIA.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,config-record-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the size of each configuration
record for the <emphasis>ibm,coherent-platform-function</emphasis>. This
value is used in H_CONTROL_CA_FUNCTION with operation Get Function
Configuration Record</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#config-records&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of the configuration records for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used in H_CONTROL_CA_FUNCTION with operation Get
Function Configuration Record.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,function-number&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the function number for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to call H_DOWNLOAD_CA_FUNCTION and download
images to the function.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies if the
<emphasis>ibm,coherent-platform-function</emphasis> is privileged.
The absence of this property or a property of 0 indicates the
function is not privileged.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis></term>
<listitem>
<para>Device ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis></term>
<listitem>
<para>Revision ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis></term>
<listitem>
<para>Class Code from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
utilizes per-process MMIO spaces. The H_ATTACH_CA_PROCESS hcall
returns MMIO address/range information. If this property is 0 or
not present, per-process MMIO is not supported.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,process-mmio-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes of the per-process MMIO space available for
each attached process. This is the same value that will be returned
in R6 for H_ATTACH_CA_FUNCTION. If the
<emphasis role="bold"><literal>ibm,process-mmio</literal></emphasis>
property is 0 or not present, this property will be 0 or not present.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>,
describes the programming model currently in effect for the coherent
platform function.</para>

<para>The value shall be one of the following:</para>

<itemizedlist spacing="compact">
<listitem>
<para>"none"</para>
</listitem>
<listitem>
<para>"dedicated-process"</para>
</listitem>
<listitem>
<para>"shared-afu-directed"</para>
</listitem>
<listitem>
<para>"shared-time-sliced"</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programming-models&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>, describes the programming
models supported by the coherent platform function.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of
strings each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
Each of the values shall be one of the possible values specified
for the
<emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis> property.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-aur&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports an acceleration utilization record (AUR). If this
property is 0 or not present, the coherent platform function
does not support an AUR.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-csrp&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports a context / save restore (CSRP). If this property is 0
or not present, the coherent platform function does not support a CSRP.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-prr&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports paged resolution responses (PRR). If this property is 0
or not present, the coherent platform function does not support
PRR.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,function-error-interrupt&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that defines the interrupt source number of the
<emphasis>ibm,coherent-platform-function </emphasis>
error interrupt. An interrupt on this source indicates an error
that is scoped to the entire
<emphasis>ibm,coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>

</section>
</section>
</section> </section>


<section xml:id="dbdoclet.50569368_56107"> <section xml:id="dbdoclet.50569368_56107">

@ -0,0 +1,360 @@
<?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.

-->
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="app_coherent_platform_facility_error_handling_recovery">
<title>Coherent Platform Facility Error Handling and Recovery</title>

<para>During the course of operation, a coherent platform function can encounter errors.
Some possible reason for errors are:</para>

<itemizedlist>
<listitem>
<para>Hardware recoverable and unrecoverable errors</para>
</listitem>
<listitem>
<para>Transient and over-threshold correctable errors</para>
</listitem>
</itemizedlist>

<para>This architecture is not meant to contain an exhaustive list of errors,
implementations can vary.</para>

<section xml:id="app_capi_error_states">
<title>Error States</title>

<informaltable frame="all" pgwide="1">
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="65*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">State</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Normal</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>Coherent platform function is operating normally. This is the
default state.</para>
</entry>
</row>
<row>
<entry>
<para>Disabled</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>Coherent platform function is operating, but all process
execution is disabled.</para>
</entry>
</row>
<row>
<entry>
<para>Temporarily Unavailable</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>Platform has initiated error recovery and the coherent
platform function is temporarily not available.</para>
</entry>
</row>
<row>
<entry>
<para>Permanently Unavailable</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>Platform has encountered a fatal error with the coherent platform
function. Recovery is impossible, without partition reboot, DLPAR
re-assignment, system reboot or hardware replacement.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

<section xml:id="app_coherent_platform_function_state_transitions">
<title>Coherent Platform Function State Transitions</title>

<informaltable frame="all" pgwide="1" >
<tgroup cols="5">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" align="center" />
<thead valign="middle">
<row>
<entry morerows="1">
<para><emphasis role="bold">Initial State</emphasis></para>
</entry>
<entry namest='c2' nameend='c5'>
<para>Final State</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">1</emphasis><?linebreak?>
<emphasis role="bold">Normal</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">2</emphasis><?linebreak?>
<emphasis role="bold">Disabled</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">3</emphasis><?linebreak?>
<emphasis role="bold">Temporarily Unavailable</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">4</emphasis><?linebreak?>
<emphasis role="bold">Permanently Unavailable</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1<?linebreak?>Normal</para>
</entry>
<entry>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<para>&#160;</para>
</entry>
<entry>
<para>Platform initiated action</para>
</entry>
<entry>
<para>Platform initiated action during recovery /
H_CONTROL_<?linebreak?>CA_FUNCTION Read Error State</para>
</entry>
<entry>
<para>Platform detected permanent error</para>
</entry>
</row>
<row>
<entry>
<para>2<?linebreak?>Disabled</para>
</entry>
<entry>
<para>H_CONTROL_<?linebreak?>CA_FUNCTION / Reset or Partition Reboot /
DLPAR re-assignment</para>
</entry>
<entry>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<para>&#160;</para>
</entry>
<entry>
<para>Platform initiated action</para>
</entry>
<entry>
<para>Platform detected permanent error</para>
</entry>
</row>
<row>
<entry>
<para>3<?linebreak?>Temporarily Unavailable</para>
</entry>
<entry>
<?dbhtml bgcolor="#dec69e" ?><?dbfo bgcolor="#dec69e" ?>
<para>Not a valid transition, must go through state 2</para>
</entry>
<entry>
<para>Platform initiated action after recovery</para>
</entry>
<entry>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<para>&#160;</para>
</entry>
<entry>
<para>Platform detected permanent error</para>
</entry>
</row>
<row>
<entry>
<para>4<?linebreak?>Permanently Unavailable</para>
</entry>
<entry>
<para>Partition reboot or DLPAR reassignment</para>
</entry>
<entry>
<?dbhtml bgcolor="#dec69e" ?><?dbfo bgcolor="#dec69e" ?>
<para>Not a valid transition</para>
</entry>
<entry>
<para>H_CONTROL_<?linebreak?>CA_FACILITY / Reset</para>
</entry>
<entry>
<?dbhtml bgcolor="#87878a" ?><?dbfo bgcolor="#87878a" ?>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

<section xml:id="app_general_error_recovery_procedure">
<title>General Error Recovery Procedure</title>

<para>The following flow is a description of the general error recovery steps
required to reset operation of the coherent platform function. This recovery
is initiated by platform firmware or after an error is detected by the OS.</para>

<orderedlist>
<listitem>
<para>If necessary, platform firmware freezes OS MMIO access for coherent
platform function, error information is col- lected and cached in platform
firmware for later retrieval by OS.</para>
</listitem>
<listitem>
<para>Platform firmware terminates and removes all processes and disables
coherent platform function if possible.</para>
</listitem>
<listitem>
<para>The error state for the coherent platform function changes to
Temporarily Unavailable.</para>
</listitem>
<listitem>
<para>Platform firmware resets and reconfigures hardware associated with
coherent platform function.</para>
</listitem>
<listitem>
<para>Platform firmware unfreezes OS MMIO access and sets coherent
platform function to Disabled.</para>
</listitem>
<listitem>
<para>OS calls H_CONTROL_CA_FUNCTION with operation of “Read Error State”
until it observes state of Disabled.</para>
</listitem>
<listitem>
<para>Optionally, OS collects any coherent platform function error data via
H_CONTROL_CA_FUNCTION with operation of “Get Error Buffer” and “Get Error
Log”.</para>
</listitem>
<listitem>
<para>OS calls H_CONTROL_CA_FUNCTION with operation of “Get Download Status”
in order to determine if a download is required for the coherent platform
function, if so, OS performs the download. After the download the coherent
platform function is still in Disabled error state.</para>
</listitem>
<listitem>
<para>OS calls <emphasis>ibm,update-nodes</emphasis> and
<emphasis>ibm,update-properties</emphasis> for the affected
coherent platform facility in order to receive current configuration values.</para>
</listitem>
<listitem>
<para>OS uses H_CONTROL_CA_FUNCTION with operation of “Reset” to change the
coherent platform function error state back to Normal.</para>
</listitem>
</orderedlist>
</section>

<section xml:id="app_os_application_detected_error">
<title>OS Application Detected Error</title>

<para>Application detects an error, using implementation dependent methods.</para>

<orderedlist>
<listitem>
<para>Application detects an error and determines a reset is necessary.</para>
</listitem>
<listitem>
<para>Application asks the OS to perform a reset to the AFU.</para>
</listitem>
<listitem>
<para>OS calls H_CONTROL_CA_FUNCTION with operation of “Reset”.</para>
</listitem>
<listitem>
<para>Platform firmware performs a reset to the coherent platform function.
See H_CONTROL_CA_FUNCTION with “Reset” operation for details.</para>
</listitem>
<listitem>
<para>OS receives return code from H_CONTROL_CA_FUNCTION indicating if the
reset was successful.</para>
</listitem>
<listitem>
<para>If necessary, the OS can performs a download of the coherent platform
function via H_DOWNLOAD_CA_FUNCTION.</para>
</listitem>
<listitem>
<para>OS then re-attachs process contexts as necessary and the application
resumes normal operation.</para>
</listitem>
<listitem>
<para>If Reset operation does not clear error, OS should signal serviceable
error to HMC and discontinue use of coherent platform function.</para>
</listitem>
</orderedlist>
</section>

<section xml:id="app_os_application_download">
<title>Application Download</title>

<para>There are some instances in which the OS would like to re-download a c
oherent platform function in operation. This could be due to unexpected
behavior or bad state.</para>

<orderedlist>
<listitem>
<para>OS resets the coherent platform function by calling
H_CONTROL_CA_FUNCTION with operation of “Reset”. The reset
clears the download state.</para>
</listitem>
<listitem>
<para>OS performs download to coherent platform function using
H_DOWNLOAD_CA_FUNCTION and after a successful download.</para>
</listitem>
<listitem>
<para>OS calls <emphasis>ibm,update-nodes</emphasis> and
<emphasis>ibm,update-properties</emphasis> for the affected
coherent platform facility in order to receive current configuration values.</para>
</listitem>
<listitem>
<para>OS can attach processes and proceed with operation.</para>
</listitem>
</orderedlist>
</section>
</appendix>

@ -336,6 +336,7 @@
<!-- Document specific appendices --> <!-- Document specific appendices -->
<xi:include href="app_service_indicators.xml"/> <xi:include href="app_service_indicators.xml"/>
<xi:include href="app_fault_v_errorlog.xml"/> <xi:include href="app_fault_v_errorlog.xml"/>
<xi:include href="app_capi_error_handling.xml"/>
<xi:include href="app_bibliography.xml"/> <xi:include href="app_bibliography.xml"/>
<xi:include href="app_glossary.xml"/> <xi:include href="app_glossary.xml"/>



@ -1563,6 +1563,37 @@ xml:lang="en">
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>

<section>
<title>Location Code for Coherent Platform Facility</title>

<para>A Coherent Platform Facility serves as the parent node for Coherent
Platform Function devices. These devices describe the virtual topology of
the coherently attached function. The location code is derived from the
physical resource loca- tion code that the coherent platform facility is
representing. For example, the form of the location code is:</para>

<itemizedlist mark="none">
<listitem>
<para>U1234.001.1054321-P1-C7</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>Location Code for Coherent Platform Function</title>
<para>A Coherent Platform Function comprises a coherently attached functional
unit. These location codes are formed by ap- pending a -Sy-Sz label which
is a zero starting decimal value that describes the resources within the
Coherent Platform Facility that are used by the Coherent Platform Function.
For example, the form of the location code is:</para>

<itemizedlist mark="none">
<listitem>
<para>U1234.001.1054321-P1-C7-S0-S1</para>
</listitem>
</itemizedlist>
</section>
</section> </section>


<section xml:id="sec_resource_location_codes"> <section xml:id="sec_resource_location_codes">

@ -2566,6 +2566,21 @@ ELSE
<xref linkend="LoPAR.Virtualization"/>.</para> <xref linkend="LoPAR.Virtualization"/>.</para>
</entry> </entry>
</row> </row>
<row>
<entry>
<para>Coherent Platform Facility</para>
</entry>
<entry>
<para>O</para>
</entry>
<entry>
<para>O</para>
</entry>
<entry>
<para>Allows partitions to resize their HPT. See
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>

@ -91,7 +91,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="7"> <entry morerows="7" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -177,7 +177,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="1"> <entry morerows="1" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -512,7 +512,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -1038,7 +1038,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="6"> <entry morerows="6" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -1120,7 +1120,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="2"> <entry morerows="2" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -1411,7 +1411,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -1485,7 +1485,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="1"> <entry morerows="1" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -1662,7 +1662,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="7"> <entry morerows="7" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -1752,7 +1752,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="1"> <entry morerows="1" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -1937,7 +1937,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="2"> <entry morerows="2" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -2269,7 +2269,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="6"> <entry morerows="6" valign="middle">
<para>&#160;</para> <para>&#160;</para>
</entry> </entry>
<entry> <entry>
@ -2620,7 +2620,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="4"> <entry morerows="4" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -2721,7 +2721,7 @@
<title>Initial Format of Work Area for <title>Initial Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title> <emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1"> <tgroup cols="1">
<colspec colname="c1" colwidth="100*" /> <colspec colname="c1" colwidth="100*" align="center" />
<thead> <thead>
<row> <row>
<entry> <entry>
@ -2763,7 +2763,7 @@
<title>Format of Work Area for <title>Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title> <emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1"> <tgroup cols="1">
<colspec colname="c1" colwidth="100*" /> <colspec colname="c1" colwidth="100*" align="center" />
<tbody> <tbody>
<row> <row>
<entry> <entry>
@ -2935,7 +2935,7 @@
<title>Format of Work Area for Subsequent Calls to <title>Format of Work Area for Subsequent Calls to
<emphasis>ibm,update-nodes</emphasis></title> <emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1"> <tgroup cols="1">
<colspec colname="c1" colwidth="100*" /> <colspec colname="c1" colwidth="100*" align="center" />
<thead> <thead>
<row> <row>
<entry> <entry>
@ -2980,10 +2980,57 @@
<xref linkend="dbdoclet.50569332_80965" /> for the value of the specified <xref linkend="dbdoclet.50569332_80965" /> for the value of the specified
<emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para> <emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> argument.</para>


</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para>The work area on the first call to
<emphasis>ibm,update-nodes</emphasis> RTAS for a given value of
<emphasis>"Scope"</emphasis> must be formatted as specified in
<xref linkend="table_initial_format_of_work_area_for_ibm_update_nodes"/>
else RTAS may return -3 "Parameter Error".</para>

<table frame="all" pgwide="1" xml:id="table_initial_format_of_work_area_for_ibm_update_nodes">
<title>Initial Format of Work Area for
<emphasis>ibm,update-nodes</emphasis> with Device Reconfiguration Scope</title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" align="center"/>
<tbody>
<row>
<entry>
<para>0x00000000 (State Variable indicates Initial call for specified <emphasis>Scope</emphasis>)</para>
</entry>
</row>
<row>
<entry>
<para>Unit Address of target device for reconfiguration</para>
</entry>
</row>
<row>
<entry>
<para>4 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>Don't Care. . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

</variablelist>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_80965"> <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_80965">
<title>Nodes That May be Reported by <title>Nodes That May be Reported by
<emphasis>ibm,update-nodes</emphasis> for a Given Value of the &#8220; <emphasis>ibm,update-nodes</emphasis> for a Given Value of the
<emphasis>Scope</emphasis>&#8221; Argument</title> &#8220;<emphasis>Scope</emphasis>&#8221; Argument</title>
<tgroup cols="3"> <tgroup cols="3">
<colspec colname="c1" colwidth="33*" /> <colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" /> <colspec colname="c2" colwidth="33*" />
@ -3005,13 +3052,13 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="7"> <entry morerows="7" valign="middle">
<para>Negative values: Platform Resource Reassignment events as <para>Negative values: Platform Resource Reassignment events as
from from
<emphasis>event-scan</emphasis> RTAS</para> <emphasis>event-scan</emphasis> RTAS</para>
</entry> </entry>
<entry> <entry>
<para>cpu</para> <para><emphasis role="bold">cpu</emphasis></para>
</entry> </entry>
<entry> <entry>
<para>0x02</para> <para>0x02</para>
@ -3019,7 +3066,7 @@
</row> </row>
<row> <row>
<entry> <entry>
<para>memory</para> <para><emphasis role="bold">memory</emphasis></para>
</entry> </entry>
<entry> <entry>
<para>0x02</para> <para>0x02</para>
@ -3027,7 +3074,7 @@
</row> </row>
<row> <row>
<entry> <entry>
<para>ibm,dynamic-reconfiguration-memory</para> <para><emphasis role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
</entry> </entry>
<entry> <entry>
<para>0x02</para> <para>0x02</para>
@ -3036,7 +3083,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,plaform-facilities</emphasis> <emphasis role="bold">ibm,plaform-facilities</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3046,7 +3093,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,random-v#</emphasis> <emphasis role="bold">ibm,random-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3056,7 +3103,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,compression-v#</emphasis> <emphasis role="bold">ibm,compression-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3066,7 +3113,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,encryption-v#</emphasis> <emphasis role="bold">ibm,encryption-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3076,7 +3123,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis> <emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3084,12 +3131,12 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="13"> <entry morerows="13" valign="middle">
<para>1 Partition Migration / Hibernation</para> <para>1 Partition Migration / Hibernation</para>
</entry> </entry>
<entry> <entry>
<para> <para>
<emphasis>root</emphasis> <emphasis role="bold">root</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3099,7 +3146,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>openprom</emphasis> <emphasis role="bold">openprom</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3109,7 +3156,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>rtas</emphasis> <emphasis role="bold">rtas</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3119,7 +3166,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>vdevice</emphasis> <emphasis role="bold">vdevice</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3129,7 +3176,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>cpu</emphasis> <emphasis role="bold">cpu</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3139,7 +3186,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>cache</emphasis> <emphasis role="bold">cache</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3149,7 +3196,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>options</emphasis> <emphasis role="bold">options</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3159,7 +3206,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>memory</emphasis> <emphasis role="bold">memory</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3168,7 +3215,7 @@
</row> </row>
<row> <row>
<entry> <entry>
<para>ibm,dynamic-reconfiguration-memory</para> <para><emphasis role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
</entry> </entry>
<entry> <entry>
<para>&lt;all&gt;</para> <para>&lt;all&gt;</para>
@ -3176,7 +3223,7 @@
</row> </row>
<row> <row>
<entry> <entry>
<para>ibm,platform-facilities</para> <para><emphasis role="bold">ibm,platform-facilities</emphasis></para>
</entry> </entry>
<entry> <entry>
<para>0x01-0x03</para> <para>0x01-0x03</para>
@ -3185,7 +3232,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,random-v#</emphasis> <emphasis role="bold">ibm,random-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3195,7 +3242,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,compression-v#</emphasis> <emphasis role="bold">ibm,compression-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3205,7 +3252,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,encryption-v#</emphasis> <emphasis role="bold">ibm,encryption-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3215,7 +3262,7 @@
<row> <row>
<entry> <entry>
<para> <para>
<emphasis>ibm,memory-utilization_instrumentation-v#</emphasis> <emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3228,7 +3275,30 @@
</entry> </entry>
<entry> <entry>
<para> <para>
<emphasis>rtas</emphasis> <emphasis role="bold">rtas</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry morerows="1" valign="middle">
<para>3 Device Reconfiguration</para>
</entry>
<entry>
<para>
<emphasis role="bold">ibm,coherent-platform-facility</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,coherent-platform-function</emphasis>
</para> </para>
</entry> </entry>
<entry> <entry>
@ -3238,9 +3308,6 @@
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</listitem>
</varlistentry>
</variablelist>


</section> </section>


@ -3326,7 +3393,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="4"> <entry morerows="4" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -3381,7 +3448,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry> <entry valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -3689,7 +3756,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="6"> <entry morerows="6" valign="middle">
<para>All negative values: Resource Reassignment events as from <para>All negative values: Resource Reassignment events as from
event-scan RTAS</para> event-scan RTAS</para>
</entry> </entry>
@ -3758,10 +3825,10 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="31"> <entry morerows="31" valign="middle">
<para>1 Partition Migration / Hibernation</para> <para>1 Partition Migration / Hibernation</para>
</entry> </entry>
<entry morerows="18"> <entry morerows="18" valign="middle">
<para> <para>
<emphasis role="bold"><literal>root</literal></emphasis> <emphasis role="bold"><literal>root</literal></emphasis>
</para> </para>
@ -3914,7 +3981,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="9"> <entry morerows="9" valign="middle">
<para> <para>
<emphasis role="bold"><literal>rtas</literal></emphasis> <emphasis role="bold"><literal>rtas</literal></emphasis>
</para> </para>
@ -3994,7 +4061,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="1"> <entry morerows="1" valign="middle">
<para> <para>
<emphasis role="bold"><literal>vdevice</literal></emphasis> <emphasis role="bold"><literal>vdevice</literal></emphasis>
</para> </para>
@ -4024,11 +4091,11 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="31"> <entry morerows="31" valign="middle">
<para>1 Partition Migration / Hibernation</para> <para>1 Partition Migration / Hibernation</para>
<para>&#160;</para> <para>&#160;</para>
</entry> </entry>
<entry morerows="20"> <entry morerows="20" valign="middle">
<para> <para>
<emphasis role="bold"><literal>cpu</literal></emphasis> <emphasis role="bold"><literal>cpu</literal></emphasis>
</para> </para>
@ -4180,7 +4247,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="4"> <entry morerows="4" valign="middle">
<para> <para>
<emphasis role="bold"><literal>cache</literal></emphasis> <emphasis role="bold"><literal>cache</literal></emphasis>
</para> </para>
@ -4244,7 +4311,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="2"> <entry morerows="2" valign="middle">
<para> <para>
<emphasis role="bold"><literal>ibm,dynamic-reconfiguration-memory</literal></emphasis> <emphasis role="bold"><literal>ibm,dynamic-reconfiguration-memory</literal></emphasis>
</para> </para>
@ -4279,7 +4346,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="3"> <entry morerows="3" valign="middle">
<para>1 Partition Migration / Hibernation</para> <para>1 Partition Migration / Hibernation</para>
<para>&#160;</para> <para>&#160;</para>
</entry> </entry>
@ -4357,6 +4424,264 @@
of that RTAS function call does not change.</para> of that RTAS function call does not change.</para>
</entry> </entry>
</row> </row>
<row>
<entry morerows="34" valign="middle">
<para>3 Device Reconfiguration</para>
</entry>
<entry morerows="10" valign="middle">
<para>
<emphasis role="bold"><literal>ibm,coherent-platform-facility</literal></emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,caia-version&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,psl-revision&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry morerows="23" valign="middle">
<para>
<emphasis role="bold"><literal>ibm,coherent-platform-function</literal></emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,max-ints-per-process&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,min-ints-per-process&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#processes&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,config-record-type&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,config-record-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,#config-records&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,error-buffer-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,scratchpad-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,supports-aur&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,supports-csrp&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,supports-prr&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,process-mmio-size&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,programming-models&#8221;</literal></emphasis>
</para>
</entry>
</row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
@ -4406,7 +4731,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -5193,7 +5518,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -5264,7 +5589,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -5423,7 +5748,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="7"> <entry morerows="7" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -5513,7 +5838,7 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry morerows="3"> <entry morerows="3" valign="middle">
<para>Out</para> <para>Out</para>
</entry> </entry>
<entry> <entry>
@ -5650,7 +5975,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="3"> <entry morerows="3" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>
@ -5920,7 +6245,7 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry morerows="5"> <entry morerows="5" valign="middle">
<para>In</para> <para>In</para>
</entry> </entry>
<entry> <entry>

@ -1274,6 +1274,22 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
more digits and no leading zeroes</para> more digits and no leading zeroes</para>
</entry> </entry>
</row> </row>
<row>
<entry>
<para>COPLATFAC</para>
</entry>
<entry>
<para>location code</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFUN</para>
</entry>
<entry>
<para>location code</para>
</entry>
</row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
@ -4192,6 +4208,52 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
</section> </section>
</section> </section>


<section xml:id="sec_isolation_of_coherent_platform_facilities">
<title>Isolation of Coherent Platform Facilities</title>

<para>Isolation of a Coherent Platform Facility (COPLATFAC) disconnects the OS
image from any of the DR connectors downstream (Coherent Platform Functions or
COPLATFUN) of the Coherent Platform Facility. To avoid the complex- ity of
gracefully managing multi-level isolation, isolation is restricted to only
“leaf” DR connectors, that is connectors that have no unisolated or usable DR
connectors below them. All COPLATFUN connectors must return unusable state (2)
during get-sensor-state before a COPLATFAC can be isolated, this is done through
set-indicator (isolation-state, isolate). The OS is responsible for removing all
memory mappings and detaching all processes potentially in use by co- herent
platform functions. If valid mappings or processes are found, the set-indicator
does not change the isolation state and returns with a Status -9001 (Valid
outstanding translation).</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_isolation_of_coherent_platform_facilities"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a
request to <emphasis>set-indicator</emphasis> (isolation-state, isolate)
would result in the isolation of one or more other DR connectors
which are currently unisolated or usable, then the
<emphasis>set-indicator</emphasis> RTAS must fail with a return code of
“Multi-level isolation error” (-9000).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_isolation_of_coherent_platform_facilities"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option combined with the LPAR
option:</emphasis> The RTAS <emphasis>set-indicator</emphasis> specifying
isolate isolation-state of a COPLATFUN DR connector type must check that
all processes associated with the function are detached, else the RTAS
routine must return with a Status -9001 (Valid outstanding translation)
and the isolation-state is not changed.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

<section xml:id="sec_set_indicator"> <section xml:id="sec_set_indicator">
<title><emphasis>set-indicator</emphasis> (dr-indicator)</title> <title><emphasis>set-indicator</emphasis> (dr-indicator)</title>
<para>Logical connectors do not have associated dr-indicators (token <para>Logical connectors do not have associated dr-indicators (token
@ -4374,6 +4436,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
power-up.</para> power-up.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector of
type CO- PLATFAC or COPLATFUN, the returned values must represent the
sub-tree for the specific coherent plat- form sub-system represented by
the COPLATFAC or COPLATFUN connector. All properties are updated with
the most recent data from the coherent platform resource.</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>


</section> </section>

File diff suppressed because it is too large Load Diff

@ -4160,7 +4160,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
the Hypervisor should wait after enqueueing the “Prepare for Suspend” the Hypervisor should wait after enqueueing the “Prepare for Suspend”
transport event on the server's command queue until receiving the transport event on the server's command queue until receiving the
H_VIOCTL READY_FOR_SUSPEND subfunction from the server. The H_VIOCTL READY_FOR_SUSPEND subfunction from the server. The
time- out value should take into account the maximum amount of timeout value should take into account the maximum amount of
time to queisce I/O operations prior to migration of the client time to queisce I/O operations prior to migration of the client
partition.</para> partition.</para>
</listitem> </listitem>
@ -4198,10 +4198,10 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
event on a VSCSI or VFC server adapter for which this function is called. If event on a VSCSI or VFC server adapter for which this function is called. If
enabled via the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, the server enabled via the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, the server
should call this H_VIOCTL READY_FOR_SUSPEND subfunction after receiving the should call this H_VIOCTL READY_FOR_SUSPEND subfunction after receiving the
“Prepare For Sus- pend” transport event and quiescing I/O operations to the “Prepare For Suspend” transport event and quiescing I/O operations to the
backing store. If the server is unable to call this subfunction within the backing store. If the server is unable to call this subfunction within the
timeout specified in the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, timeout specified in the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction,
the migration op- eration on the client partition will be aborted. the migration operation on the client partition will be aborted.
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Validate that the unit-address corresponds to a VSCSI or VFC <para>Validate that the unit-address corresponds to a VSCSI or VFC

Loading…
Cancel
Save