Collapse 5 subdocs back into a single document. Clean build. Tag work needed.

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
pull/2/head
Jeff Scheel 5 years ago
parent 863f92baaf
commit 809fc06d01

@ -29,11 +29,11 @@
<orderedlist>

<!-- TODO: Uncomment documents needing referencing and comment out local document -->
<!--listitem>
<listitem>
<para><anchor xml:id="LoPAR.Platform"
xreflabel="Linux on Power Architecture Reference: Platform"/><citetitle>
Linux on Power Architecture Reference: Platform and Device Tree</citetitle></para>
</listitem-->
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.DeviceTree"
@ -281,4 +281,3 @@
</orderedlist>

</appendix>

@ -15,7 +15,7 @@
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix 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"
@ -24,7 +24,7 @@

<title>CMO Characteristics Definitions</title>

<para>This chapter defines the string that is returned by the
<para>This appendix defines the string that is returned by the
<emphasis>ibm,get-system-parameter</emphasis> RTAS call when the parameter
token value of 44 (CMO Characteristics) is specified on the
<emphasis>ibm,get-system-parameter</emphasis> RTAS call as per
@ -170,4 +170,4 @@
</tgroup>
</table>
</section>
</chapter>
</appendix>

@ -15,14 +15,14 @@
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en">

<title>Firmware Assisted Dump Data Format</title>

<para>This Appendix documents the dump data format, in support of the
<para>This appendix documents the dump data format, in support of the
Configure Platform Assisted Kernel Dump option in
<xref linkend="LoPAR.Virtualization" />.</para>

@ -6279,4 +6279,4 @@
<para />
</section>

</chapter>
</appendix>

@ -15,12 +15,50 @@
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix 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:id="dbdoclet.50569374_59715"
xml:lang="en">
<title>Processor Architecture Binding</title>
<title>PA Processor Binding</title>

<section>
<title>Purpose of this Binding</title>

<para>This appendix specifies the application of OF to a PA Processor (which covers
all PowerPC processors and their suc- cessors), including requirements and
practices to support unique firmware specific to a PA Processor. The core
requirements and practices specified by OF must be augmented by processor-specific
requirements to form a complete specification for the firmware implementation
for a PA processor. This appendix establishes such additional requirements
pertaining to the processor and the support required by OF.</para>
</section>

<section>
<title>Overview</title>

<para>This appendix specifies the application of
<emphasis><xref linkend="dbdoclet.50569387_45524" /></emphasis>
to computer systems that use the PA instruction set, including
instruction-set-specific requirements and practices for debugging, client
program interface and data formats. An implementation of OF for PA shall
implement the core requirements as defined in
<xref linkend="dbdoclet.50569387_45524" /> and the PA-specific extensions
described in this binding.</para>

<para>This appendix addresses
<xref linkend="dbdoclet.50569387_99718" />. The descriptions that follow,
and the relevant sections describing translation features for this binding,
assume that the system&#8217;s PA processor(s) implement the entire PA
(that is, all books of
<xref linkend="dbdoclet.50569387_99718" />). Some processors may implement
different Book II-III features; such processors may need a variant of this
binding describing the differences to the mapping functions, etc.</para>

</section>

<xi:include href="sec_pa_processor_binding_terms.xml"/>

<section>
<title>Data Formats and Representations</title>
@ -4386,4 +4424,4 @@

</section>

</chapter>
</appendix>

@ -15,13 +15,57 @@
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix 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.50569368_91814">
<title>System Binding</title>

<para>This appendix specifies the application of OF to a PAPR System, including
requirements and practices to support unique hardware and firmware specific to the
platform implementation. The core requirements and practices specified by OF must
be augmented by system-specific requirements to form a complete specification for
the firmware implementation of a PAPR System. This appendix establishes such
additional requirements pertaining to the platform and the support required by OF.</para>

<section>
<title>Overview</title>

<para>This appendix specifies the application of
<emphasis>IEEE Std 1275-1994 Standard for Boot (Initialization,
Configuration) Firmware, Core Practices and Requirements</emphasis>,
<emphasis>Core Errata, IEEE P1275.7</emphasis> and appropriate OF Standards
for LoPAR computer systems, including practices for client program
interface and data formats.</para>

<section>
<title>General Requirements for OF</title>
<para>An OF implementation for an LoPAR platform shall implement the
core requirements as defined in
<xref linkend="dbdoclet.50569387_45524" />, core errata
<xref linkend="dbdoclet.50569387_14175" />, the PA Processor-specific
extensions described in
<xref linkend="dbdoclet.50569374_59715" />, other appropriate bindings
and/or recommended practices contained in the references (see
<xref linkend="dbdoclet.50569387_27251" />), and the LoPAR Binding
specific extensions described in this appendix.</para>
<para>In addition, an OF implementation for an LoPAR platform shall
implement the
<emphasis>Device Interface</emphasis>,
<emphasis>Client Interface</emphasis> and
<emphasis>User Interface</emphasis> as defined in
<xref linkend="dbdoclet.50569387_45524" />.</para>
<para>Some LoPAR Binding property names exceed the OF Base specification
limit of 31 characters. LoPAR OF implementations shall support property
names of at least 47 characters.</para>
</section>

</section>

<xi:include href="sec_papr_binding_terms.xml"/>

<section>
<title>LoPAR Boot Flow</title>

@ -12197,4 +12241,4 @@ else

</section>

</chapter>
</appendix>

@ -1,8 +1,8 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569383_58396">
<title>Platform Dependent hcall()s</title>

<para>This chapter defines the set of hypervisor calls (hcall()s) that are
<para>This appendix defines the set of hypervisor calls (hcall()s) that are
platform dependent. The existence and/or implementation of the hcall() can
vary between firmware releases and between hardware platforms.</para>
<section>
@ -614,4 +614,4 @@ hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */
</simplesect>
</section>
</section>
</chapter>
</appendix>

@ -1,10 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title>SPLPAR Characteristics Definitions</title>
<section>
<title xml:id="dbdoclet.50569367_15730">SPLPAR Characteristics Definitions</title>

<para>This chapter defines the string that is returned by the
<para>This appendix defines the string that is returned by the
ibm,get-system-parameter RTAS call when the parameter token value of 20
(SPLPAR Characteristics) is specified on the ibm,get-system-parameter RTAS
call as per <xref linkend="LoPAR.RTAS" />.</para>
@ -532,4 +532,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
</orderedlist>
</para>
</section>
</chapter>
</appendix>

@ -1,10 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title xml:id="dbdoclet.50569384_75285">A Protocol for VNIC Communications</title>

<section>
<title>Introduction</title>
<para>The VNIC protocol defined in this chapter defines the protocol to be
<para>The VNIC protocol defined in this appendix defines the protocol to be
used with VNIC virtual IOA, as defined in
<xref linkend="dbdoclet.50569366_19541" />. VNIC provides a mechanism which
minimizes the number of times data is copied within the memory of the
@ -9887,4 +9887,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">

</section>
</section>
</chapter>
</appendix>

@ -1,10 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569379_75285">
<title>A Protocol for VSCSI Communications</title>

<section>
<title>Introduction</title>
<para>The purpose of this chapter is to define the protocol used by
<para>The purpose of this appendix is to define the protocol used by
virtual SCSI (vscsi) client drivers and vscsi server drivers in sufficient
detail to ensure compatibility between unlike operating systems
implementing these features. The SCSI Architecture Model (SAM-2) defines
@ -1195,4 +1195,4 @@ unsigned int cap_type;

</section>
</section>
</chapter>
</appendix>

@ -15,13 +15,13 @@
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="ch_virtual_trusted_platform_module">
<title>Virtual Trusted Platform Module (VTPM)</title>

<section>
<title>A protocol for VTPM communications</title>
<para>The protocol defined in this section is to be used with the VTPM as defined in
<para>The protocol defined in this appendix is to be used with the VTPM as defined in
<xref linkend="sec_virtual_trusted_platform_module" />.
The VTPM provides the services of a TPM device to an associated client partition,
the primary use of a VTPM is to enable software in the partition to perform a
@ -2369,4 +2369,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="ch_v
</section>
</section>
</section>
</chapter>
</appendix>

@ -1,10 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569375_64200">
<title>A Protocol for a Virtual TTY Interface</title>

<section>
<title>Overview</title>
<para>This chapter defines a protocol to support partition use of a
<para>This appendix defines a protocol to support partition use of a
physical serial port using a virtual TTY (VTY) interface. A protocol is
required to send control and status information of the physical device
using a data only transport.</para>
@ -1038,4 +1038,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
device tree node to communicate an appropriate time-out value.</para>

</section>
</chapter>
</appendix>

@ -1,4 +1,4 @@
<chapter xmlns="http://docbook.org/ns/docbook"
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title>A Protocol for VMC Communications</title>

@ -1298,4 +1298,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
</figure>
</section>
</section>
</chapter>
</appendix>

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

-->
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="bk_main">

<!-- TODO: When ready to publish document, remove the 'status="draft"' statement from the book object above. -->

<title>Linux on Power Architecture Reference</title>
<subtitle>A PAPR Linux Subset</subtitle>

<info>
<author>
<personname>
<surname>System Software Work Group</surname>
</personname>
<email>syssw-chair@openpowerfoundation.org</email>
<affiliation>
<orgname>OpenPOWER Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2016, 2018, 2020</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 0.5_pre6</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

<legalnotice role="apache2">

<annotation>
<remark>Copyright details are filled in by the template.</remark>
</annotation>
</legalnotice>

<!-- TODO: Update the following text with the correct document description (first paragraph),
Work Group name, and Work Product track (both in second paragraph). -->
<abstract>
<para>The purpose of this document is to provide firmware and software
architectural details associated with an OpenPOWER Systems.
The base content for this document were contributed to the OpenPOWER Foundation in the
<citetitle>IBM Linux on Power Architecture Platform Reference (LoPAPR) Draft</citetitle>
document which detailed Linux running on PowerVM. While this information is not always
immediately applicable to new OpenPOWER modes of bare metal or KVM, many of the
concepts and interfaces remain in some form. Until such time as the document addresses
these new OpenPOWER modes and components, it will remain versioned less than 1.0. It should
also be noted that the original document had numerous contributors inside IBM.</para>

<para>This document is a Standard Track, Work Group Specification work product owned by the
System Software Workgroup and handled in compliance with the requirements outlined in the
<citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document. It was
created using the <citetitle>Master Template Guide</citetitle> version 0.9.5. Comments,
questions, etc. can be submitted to the public mailing list for this document at
<link xlink:href="mailto:syssw-linux_architecture_ref@mailinglist.openpowerfoundation.org">syssw-linux_architecture_ref@mailinglist.openpowerfoundation.org</link>.</para>
</abstract>

<revhistory>
<!-- TODO: Update as new revisions created -->
<revision>
<date>2020-04-20</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 0.5_pre6 - Re-merge 5 sub-docs back into one matching PAPR. No technical updates.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2020-04-06</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 0.5_pre5 - Updates to include latest PAPR ACRs (2.9) as follows:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Add H_VIOCTL subfunctions for VNIC failover support</para>
</listitem>
<listitem>
<para>Add H_VIOCTL subfunction for virtual ethernet MAC scan functionality</para>
</listitem>
<listitem>
<para>Add H_VIOCTL subfunctions for virtual scsi and FC mobility preparation functionality</para>
</listitem>
<listitem>
<para>ibm,current-associativity-domain property</para>
</listitem>
<listitem>
<para>HPT resizing option - KVM only</para>
</listitem>
<listitem>
<para>Add Coherent Platform Facilities (CAPI)</para>
</listitem>
<listitem>
<para>XIVE Exploitation</para>
</listitem>
<listitem>
<para>Add 'OCC online/offline' events to 'IE' error log subsection</para>
</listitem>
<listitem>
<para>LPM Redundancy Phase II: Redundancy</para>
</listitem>
<listitem>
<para>Add optional sub-queue support to VFC on P9 and newer</para>
</listitem>
<listitem>
<para>Increase max num-entries for H_SEND_SUB_CRQ_INDIRECT to 128</para>
</listitem>
<listitem>
<para>Add Virtual Serial Multiplex adapter interfaces</para>
</listitem>
<listitem>
<para>Maximum size of Dispatch Trace Log Buffer</para>
</listitem>
<listitem>
<para>Eliminate requirement for clearing TCP checksum field for ILLAN checksum calculation</para>
</listitem>
<listitem>
<para>Continued Extension of H_Send_Logical_LAN for large send packets</para>
</listitem>
<listitem>
<para>Add LPM Capablity keyword to RTAS AIX Support system parameter</para>
</listitem>
<listitem>
<para>XIVE Exploitation addition: Add ESB Reset Status to RTAS ibm,read-slot-reset-state2</para>
</listitem>
<listitem>
<para>Add NVDIMM Protection and Encryption State system parameters</para>
</listitem>
<listitem>
<para>Change or Remove 0x9 and 0xA event subtypes for 'IE' error log subsection</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Additional, post PAPR 2.9 ACRs as follows:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Reserve a range of hcalls to to support Ultravisor</para>
</listitem>
<listitem>
<para>Add New CAS Bit For SRIOV Virtual Function (VF) Dynamic DMA Window (DDW) Support</para>
</listitem>
<listitem>
<para>Updates to support vTPM 2.0</para>
</listitem>
<listitem>
<para>Update XIVE Legacy hcalls to add H_Function</para>
</listitem>
<listitem>
<para>Add NVDIMM Secure Erase Command system parameter</para>
</listitem>
<listitem>
<para>Update H_REGISTER_VPA to add H_STATE return code for VPA and SLB shadow buffer.</para>
</listitem>
<listitem>
<para>Extend Firmware Assisted Dump for ISA Version 3.0</para>
</listitem>
<listitem>
<para>Add a new return code, H_NOT_AVAILABLE, to start-cpu rtas call</para>
</listitem>
<listitem>
<para>Document already-implemented NVRAM variables</para>
</listitem>
<listitem>
<para>Update ibm,dynamic-memory-vN flags to include a "Hotplugged Memory" flag</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2019-01-08</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 0.5_pre4 - Update document type to Work Group Note. Final review ready.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2018-07-30</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 0.5_pre3 - Updates to documentation in preparation for System SW WG review:</para>
<orderedlist spacing="compact">
<listitem>
<para>Reset document version to 0.5</para>
</listitem>
<listitem>
<para>Improved Abstract</para>
</listitem>
</orderedlist>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2017-10-11</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows:</para>
<itemizedlist spacing="compact">
<listitem>
<para>ISA 2.07 privileged doorbell extensions (9/16/2012)</para>
</listitem>
<listitem>
<para>POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012)</para>
</listitem>
<listitem>
<para>Enable Multiple Redirected RDMA mappings per page (3/5/2013)</para>
</listitem>
<listitem>
<para>Add Block Invalidate Option (3/5/2013)</para>
</listitem>
<listitem>
<para>Implementation Dependent Optimizations (3/13/2013)</para>
</listitem>
<listitem>
<para>System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013)</para>
</listitem>
<listitem>
<para>New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013)</para>
</listitem>
<listitem>
<para>Remove Client-Architecture-Support bit for UUID option (4/16/2013)</para>
</listitem>
<listitem>
<para>AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013)</para>
</listitem>
<listitem>
<para>Add VNIC Server (5/24/2014)</para>
</listitem>
<listitem>
<para>VPA changes for P8 (EBB) (5/24/2013)</para>
</listitem>
<listitem>
<para>Add an hcall to clean up the entire MMU hashtable (11/20/2013)</para>
</listitem>
<listitem>
<para>Add LPCR[ILE] support to H_SET_MODE (5/31/2013)</para>
</listitem>
<listitem>
<para>New Root Node Properties (1/12/2016)</para>
</listitem>
<listitem>
<para>Extended Firmware Assisted Dump for P8 Registers (1/24/2014)</para>
</listitem>
<listitem>
<para>Sufficient H_COP_OP output buffer (6/21/2014)</para>
</listitem>
<listitem>
<para>Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014)</para>
</listitem>
<listitem>
<para>Extend H_GET_MPP_X reporting coalesced pages (8/24/2014)</para>
</listitem>
<listitem>
<para>Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015)</para>
</listitem>
<listitem>
<para>Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015)</para>
</listitem>
<listitem>
<para>Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015)</para>
</listitem>
<listitem>
<para>Additional System Parameter to read LPAR Name string (10/7/2015)</para>
</listitem>
<listitem>
<para>Redesign of properties for DRC information and dynamic memory (7/23/2015)</para>
</listitem>
<listitem>
<para>Add additional logical loction code sections (3/4/2016)</para>
</listitem>
<listitem>
<para>Add ibm,vnic-client-mac to support vNIC failover (2/29/2016)</para>
</listitem>
<listitem>
<para>hcall for registering the process table (3/21/2016)</para>
</listitem>
<listitem>
<para>New device tree property for UUID (3/21/2016)</para>
</listitem>
<listitem>
<para>Changes for Hotplug RTAS Events (10/24/2016)</para>
</listitem>
<listitem>
<para>Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016)</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2016-05-04</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.0_pre1 - initial conversion from IBM document. Extracted from
Linux on Power Architecture Platform Reference (LoPAPR) version 1.1 dated March 24,
2016 -- Chapter 1 (Introduction), Chapter 2 (System Requirements),
Chapter 3 (Address Map), Chapter 4 (I/O Bridges and Topology),
Chapter 5 (Processors and Memory), Chapter 6 (Interrupt Controller),
Chapter 8 (Non-volatile memory), Chapter 9 (I/O Devices),
Chapter 11 (The Symmetric Multiprocessor Option), Chapter 12 (Product Topology),
and Appendix H (Non-Uniform Memory Access [NUMA] Option).</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>

<!-- The ch_preface.xml file is required by all documents -->
<xi:include href="../../Docs-Master/common/ch_preface.xml"/>
<xi:include href="ch_LoPAPR_preface.xml"/>

<!-- Chapter heading files -->
<xi:include href="ch_introduction.xml"/>
<xi:include href="ch_system_reqs.xml"/>
<xi:include href="ch_address_map.xml"/>
<xi:include href="ch_processors_memory.xml"/>
<xi:include href="ch_io_topology.xml"/>
<xi:include href="ch_interrupt_controller.xml"/>
<xi:include href="ch_rtas.xml"/>
<xi:include href="ch_nonvolatile_memory.xml"/>
<xi:include href="ch_io_devices.xml"/>
<xi:include href="ch_notifications.xml"/>
<xi:include href="ch_smp.xml"/>
<xi:include href="ch_product_topology.xml"/>
<xi:include href="ch_dynamic_reconfig.xml"/>
<xi:include href="ch_lpar_option.xml"/>
<xi:include href="ch_numa.xml"/>
<xi:include href="ch_service_indicators.xml"/>
<xi:include href="ch_virtual_io.xml"/>

<!-- Document specific appendices -->
<xi:include href="app_splar.xml"/>
<xi:include href="app_papr_binding.xml"/>
<xi:include href="app_pa_processor_binding.xml"/>
<xi:include href="app_virtual_tty.xml"/>
<xi:include href="app_virtual_scsi.xml"/>
<xi:include href="app_vmc_comm.xml"/>
<xi:include href="app_firmware_dump.xml"/>
<xi:include href="app_eeh_handling.xml"/>
<xi:include href="app_cmo_def.xml"/>
<xi:include href="app_platform_hcalls.xml"/>
<xi:include href="app_virtual_nic.xml"/>
<xi:include href="app_virtual_tpm.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_glossary.xml"/>

<!-- The app_foundation.xml appendix file is required by all documents. -->
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>

<xi:include href="app_EOD.xml"/>

</book>

@ -23,9 +23,9 @@
<title>About This Document</title>
<?dbhtml stop-chunking?>

<xi:include href="sec_LoPAR_goals.xml"/>
<xi:include href="sec_LoPAR_audience.xml"/>
<xi:include href="sec_LoPAR_reading.xml"/>
<xi:include href="sec_LoPAR_conventions.xml"/>
<xi:include href="sec_LoPAPR_goals.xml"/>
<xi:include href="sec_LoPAPR_audience.xml"/>
<xi:include href="sec_LoPAPR_reading.xml"/>
<xi:include href="sec_LoPAPR_conventions.xml"/>

</preface>

@ -4205,252 +4205,252 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
</varlistentry>
</variablelist>
</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>
</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>
<section xml:id="sec_set_indicator">
<title><emphasis>set-indicator</emphasis> (dr-indicator)</title>
<para>Logical connectors do not have associated dr-indicators (token
value 9002). An attempt to set the state of such an indicator results in
a &#8220;No such indicator implemented&#8221; return status.
</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_isolation_of_coherent_platform_facilities"
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_set_indicator"
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>
<para><emphasis role="bold">For all LRDR options:</emphasis> The calling of
<emphasis>set-indicator</emphasis> with a token value of 9002
(dr-indicator) and an index representing a logical connector must fail
with a return code of &#8220;No such indicator implemented&#8221;
(-3).</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</section>

</section>

<section xml:id="sec_set_indicator">
<title><emphasis>set-indicator</emphasis> (dr-indicator)</title>
<para>Logical connectors do not have associated dr-indicators (token
value 9002). An attempt to set the state of such an indicator results in
a &#8220;No such indicator implemented&#8221; return status.
</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_set_indicator"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> The calling of
<emphasis>set-indicator</emphasis> with a token value of 9002
(dr-indicator) and an index representing a logical connector must fail
with a return code of &#8220;No such indicator implemented&#8221;
(-3).</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_ibm_configure_connnector">
<title><emphasis>ibm,configure-connector</emphasis></title>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call is used to return
to the OS the device tree nodes and properties associated with the newly
un-isolated logical resources and configure them for use.</para>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call used against a
logical DR connector can encounter other logical DR connectors or
physical DR connectors below it in the tree. If a logical connector is
encountered below a logical connector that is being configured, the
<emphasis>ibm,configure-connector</emphasis> RTAS call will not configure
the sub-tree, if it is not owned by the OS (where owned refers to a DR
connector that would return a DR entity usable, for a
<emphasis>get-sensor</emphasis> dr-entity-sense sensor). If a physical
connector is encountered, then the sub-tree below the physical connector
may or may not be configured, depending on the implementation.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The requirements of this section
specify the minimum sub-tree contents returned for various connector
types. Implementations may optionally return other valid previously
reported nodes that represent the current configuration of the device
tree. Previously reported nodes may not have any changes from their
previously reported state. A node that was removed from the configuration
due to a DR operation and returns due to a subsequent DR operation is not
considered to have been previously reported. It is the caller's
responsibility to recognize previously reported nodes.</para>
<section xml:id="sec_ibm_configure_connnector">
<title><emphasis>ibm,configure-connector</emphasis></title>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call is used to return
to the OS the device tree nodes and properties associated with the newly
un-isolated logical resources and configure them for use.</para>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call used against a
logical DR connector can encounter other logical DR connectors or
physical DR connectors below it in the tree. If a logical connector is
encountered below a logical connector that is being configured, the
<emphasis>ibm,configure-connector</emphasis> RTAS call will not configure
the sub-tree, if it is not owned by the OS (where owned refers to a DR
connector that would return a DR entity usable, for a
<emphasis>get-sensor</emphasis> dr-entity-sense sensor). If a physical
connector is encountered, then the sub-tree below the physical connector
may or may not be configured, depending on the implementation.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The requirements of this section
specify the minimum sub-tree contents returned for various connector
types. Implementations may optionally return other valid previously
reported nodes that represent the current configuration of the device
tree. Previously reported nodes may not have any changes from their
previously reported state. A node that was removed from the configuration
due to a DR operation and returns due to a subsequent DR operation is not
considered to have been previously reported. It is the caller's
responsibility to recognize previously reported nodes.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector that is
isolated,
<emphasis>ibm,configure-connector</emphasis> must immediately return
configuration complete.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector that is
isolated,
<emphasis>ibm,configure-connector</emphasis> must immediately return
configuration complete.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If the connector index refers
to a connector that would return a &#8220;DR entity unusable&#8221;
status (2), &#8220;DR entity available for exchange&#8221; status (3), or
&#8220;DR entity available for recovery&#8221; status (4) to the
<emphasis>get-sensor</emphasis> dr-entity-sense token, the
<emphasis>ibm,configure-connector</emphasis> RTAS call must return
&#8220;-9003: Cannot configure - Logical DR connector unusable, available
for exchange, or available for recovery&#8221; on the first call without
any configuration action taken on the DR connector.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If the connector index refers
to a connector that would return a &#8220;DR entity unusable&#8221;
status (2), &#8220;DR entity available for exchange&#8221; status (3), or
&#8220;DR entity available for recovery&#8221; status (4) to the
<emphasis>get-sensor</emphasis> dr-entity-sense token, the
<emphasis>ibm,configure-connector</emphasis> RTAS call must return
&#8220;-9003: Cannot configure - Logical DR connector unusable, available
for exchange, or available for recovery&#8221; on the first call without
any configuration action taken on the DR connector.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-3.</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
CPU,
the returned sub-tree must consist of the specific
cpu-node, its children, and any referenced nodes that had not been
previously reported (such as L2 and L3 caches etc.) all containing the
properties as would be contained in those nodes had they been available
at boot time.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> Future platforms that support
concurrent maintenance of caches, will require that high level cache
nodes (L2, L3 etc.) are added by
<emphasis>ibm,configure-connector</emphasis> such that their properties
can change as new/repaired hardware is added to the platform. Therefore,
it is the OS's responsibility when isolating a CPU to purge any
information it may have regarding an orphaned high level cache node. The
OS may use the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property to selectively
remove caches when a processor is removed. The platform considers any
high level cache that is newly referenced (reference count for this
partition goes from 0 to 1) to have been previously unreported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-3.</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
CPU,
the returned sub-tree must consist of the specific
cpu-node, its children, and any referenced nodes that had not been
previously reported (such as L2 and L3 caches etc.) all containing the
properties as would be contained in those nodes had they been available
at boot time.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> Future platforms that support
concurrent maintenance of caches, will require that high level cache
nodes (L2, L3 etc.) are added by
<emphasis>ibm,configure-connector</emphasis> such that their properties
can change as new/repaired hardware is added to the platform. Therefore,
it is the OS's responsibility when isolating a CPU to purge any
information it may have regarding an orphaned high level cache node. The
OS may use the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property to selectively
remove caches when a processor is removed. The platform considers any
high level cache that is newly referenced (reference count for this
partition goes from 0 to 1) to have been previously unreported.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis role="bold"><literal>ibm,configure-connector</literal></emphasis> specifies a connector of type
MEM,
the returned sub-tree must consist of the specific
<emphasis role="bold"><literal>ibm,memory-region</literal></emphasis> node containing the properties as
would be contained in that node had it been available at boot
time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis role="bold"><literal>ibm,configure-connector</literal></emphasis> specifies a connector of type
MEM,
the returned sub-tree must consist of the specific
<emphasis role="bold"><literal>ibm,memory-region</literal></emphasis> node containing the properties as
would be contained in that node had it been available at boot
time.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-5.</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
PHB or SLOT, then all of the following must be true:
<orderedlist numeration="loweralpha">
<listitem>
<para>The returned values must represent the sub-tree for the specific
I/O sub-system represented by the connector, except for entities below
any DR connectors (logical or physical) which are below the connector
which is the target of the ibm,configure-connector operation (that is,
the ibm,configure-connector operation stops at any DR connector).</para>
</listitem>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-5.</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
PHB or SLOT, then all of the following must be true:
<orderedlist numeration="loweralpha">
<listitem>
<para>The returned values must represent the sub-tree for the specific
I/O sub-system represented by the connector, except for entities below
any DR connectors (logical or physical) which are below the connector
which is the target of the ibm,configure-connector operation (that is,
the ibm,configure-connector operation stops at any DR connector).</para>
</listitem>

<listitem>
<para>The sub-tree must consist of the specific node and its children
all containing the properties as would be contained in those nodes had
they been available at boot time, including (if they exist) built-in PCI
IOAs.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<listitem>
<para>The sub-tree must consist of the specific node and its children
all containing the properties as would be contained in those nodes had
they been available at boot time, including (if they exist) built-in PCI
IOAs.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-6.</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
SLOT,
the returned values must represent the sub-tree for
the specific I/O sub-system represented by the SLOT connector, and the
sub-tree must consist of the specific
<emphasis role="bold"><literal>/pci</literal></emphasis> node and its children all containing the
properties as would be contained in those nodes had they been available
at boot time, except for the PCI IOA nodes assigned to the OS image that
contain the same properties as they would following a PCI hot plug
operation (see
<xref linkend="dbdoclet.50569342_67543" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-6.</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
SLOT,
the returned values must represent the sub-tree for
the specific I/O sub-system represented by the SLOT connector, and the
sub-tree must consist of the specific
<emphasis role="bold"><literal>/pci</literal></emphasis> node and its children all containing the
properties as would be contained in those nodes had they been available
at boot time, except for the PCI IOA nodes assigned to the OS image that
contain the same properties as they would following a PCI hot plug
operation (see
<xref linkend="dbdoclet.50569342_67543" />).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a platform implementation
powers-up and configures physical DR entities in the sub-tree under a
logical DR connector, then a request to
<emphasis>ibm,configure-connector</emphasis> of the logical DR connector
must use the return status of 990x from the
<emphasis>ibm,configure-connector</emphasis> call, as necessary, during
the DR entity power-up sequence(s) and must control any power-up and
sequencing requirements, as would be done by the platform during platform
power-up.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a platform implementation
powers-up and configures physical DR entities in the sub-tree under a
logical DR connector, then a request to
<emphasis>ibm,configure-connector</emphasis> of the logical DR connector
must use the return status of 990x from the
<emphasis>ibm,configure-connector</emphasis> call, as necessary, during
the DR entity power-up sequence(s) and must control any power-up and
sequencing requirements, as would be done by the platform during platform
power-up.</para>
</listitem>
</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>
<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>

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

@ -25,6 +25,7 @@
<?dbhtml stop-chunking?>

<xi:include href="sec_error_introduction.xml"/>
<xi:include href="sec_error_reporting.xml"/>
<xi:include href="sec_rtas_error_classes.xml"/>
<xi:include href="sec_rtas_error_reporting.xml"/>
<xi:include href="sec_error_codes.xml"/>
</chapter>

@ -1594,177 +1594,177 @@ xml:lang="en">
</listitem>
</itemizedlist>
</section>
</section>

<section xml:id="sec_resource_location_codes">
<title>Resource Location Codes</title>

<para>The resource location label consists of the
prefix 'R' followed by a non-zero decimal number. A
resource location code identifies a chip or function
embedded on a FRU. There may be multiple
resources associated with a FRU. The numbering of the
resources on a particular FRU should match
the left to right, top to bottom positioning of the
resources on the FRU when the FRU is in a typical
service position.</para>

<para>It should be noted that embedded adapters with
internal ports existed prior to introduction of the
resource label. Use of the resource label for unique
partitionable endpoint identification may or may
not be retrofitted to those adapters as they are
carried forward to new platforms.</para>
</section>
<section xml:id="sec_resource_location_codes">
<title>Resource Location Codes</title>

<para>The resource location label consists of the
prefix 'R' followed by a non-zero decimal number. A
resource location code identifies a chip or function
embedded on a FRU. There may be multiple
resources associated with a FRU. The numbering of the
resources on a particular FRU should match
the left to right, top to bottom positioning of the
resources on the FRU when the FRU is in a typical
service position.</para>

<para>It should be noted that embedded adapters with
internal ports existed prior to introduction of the
resource label. Use of the resource label for unique
partitionable endpoint identification may or may
not be retrofitted to those adapters as they are
carried forward to new platforms.</para>
</section>

<section xml:id="sec_multiple_frus_same_physical_space">
<title>Multiple FRUs In The Same Physical Space</title>

<para>A physical location code is tied to the connector
that a FRU plugs into. If two different parts with
different part numbers can plug into the same connector,
both parts will have the same location code.
However, if two different parts can plug into two
different connectors but share the same physical
space when either is installed, those parts should
each have a different location code. For example, if
two different GX adapters (such as the Bjorn IB adapter
and Newcombe PCI slot riser on Jupiter-IOC)
connect to the same planar using the same connector,
they should both be assigned the same location
code. But if a GX adapter or a PCI adapter can be
installed on a planar, but not both at the same time
as they both can't fit at the same time given the
placement of the connectors on the planar, both slots
should be assigned unique location codes.</para>
</section>
<section xml:id="sec_multiple_frus_same_physical_space">
<title>Multiple FRUs In The Same Physical Space</title>

<para>A physical location code is tied to the connector
that a FRU plugs into. If two different parts with
different part numbers can plug into the same connector,
both parts will have the same location code.
However, if two different parts can plug into two
different connectors but share the same physical
space when either is installed, those parts should
each have a different location code. For example, if
two different GX adapters (such as the Bjorn IB adapter
and Newcombe PCI slot riser on Jupiter-IOC)
connect to the same planar using the same connector,
they should both be assigned the same location
code. But if a GX adapter or a PCI adapter can be
installed on a planar, but not both at the same time
as they both can't fit at the same time given the
placement of the connectors on the planar, both slots
should be assigned unique location codes.</para>
</section>

<section xml:id="sec_pcie_attached_io_drawers">
<title>PCI-E Attached I/O Drawers</title>

<para>A PCI-E attached I/O drawer is an I/O drawer that
attaches to a GX adapter in the CEC via PCI-E
cables (as opposed to RIO or IB cables). There are two
different types of PCI-E attached I/O drawers:
ones where PHB(s) on the GX adapter connect directly
to I/O devices in the drawer and ones where the
PHB(s) on the GX adapter connect to switches (or other
fan-out logic) in the I/O drawer. In the former
case, the partitionable endpoint (PE) is the logical
PHB connection to the device. In the latter case, the
PEs are the slots wired to the downstream switch ports.</para>

<para>For GX cards whose PHBs connect directly to
devices in the I/O drawer (such as Bluehawk), the
location code and DRC name of the I/O slot partitionable
endpoint will be of the form Ucec-Pw-Cx-
Ty-Lz. Here, Ucec is the type/model/serial of the CEC
that contains the GX adapter, Pw is the planar
that contains the GX adapter, Cx is the GX adapter,
Ty is one of the ports on the adapter, and Lz is a
logical label representing a logical PCI-e connection
to an I/O device at the other end of the PCI-e
cable plugged into that port (note that there may be
multiple Cx labels if the GX adapter doesn't plug
directly into the planar in the system in question).
This location code and DRC name will be generated
by system firmware for each PE on each GX adapter that
is installed in the system and that supports
direct-connect drawers (i.e. drawers without a PCI-E
switch in them). The location code and DRC
name will be generated regardless of whether or not a
PCI-E cable is attached to the GX adapter.
It is permissible to append additional labels beyond
the L label to create different location codes for
FRUs/devices downstream from the I/O device in the
drawer that is attached to the PCI-e cable. It is
not required that all subsequent labels be logical labels.</para>

<para>For GX cards whose ports connect to a PCI-E switch
in an I/O drawer via PCI-E cables, the location
code format has not yet been defined.</para>
</section>
<section xml:id="sec_pcie_attached_io_drawers">
<title>PCI-E Attached I/O Drawers</title>

<para>A PCI-E attached I/O drawer is an I/O drawer that
attaches to a GX adapter in the CEC via PCI-E
cables (as opposed to RIO or IB cables). There are two
different types of PCI-E attached I/O drawers:
ones where PHB(s) on the GX adapter connect directly
to I/O devices in the drawer and ones where the
PHB(s) on the GX adapter connect to switches (or other
fan-out logic) in the I/O drawer. In the former
case, the partitionable endpoint (PE) is the logical
PHB connection to the device. In the latter case, the
PEs are the slots wired to the downstream switch ports.</para>

<para>For GX cards whose PHBs connect directly to
devices in the I/O drawer (such as Bluehawk), the
location code and DRC name of the I/O slot partitionable
endpoint will be of the form Ucec-Pw-Cx-
Ty-Lz. Here, Ucec is the type/model/serial of the CEC
that contains the GX adapter, Pw is the planar
that contains the GX adapter, Cx is the GX adapter,
Ty is one of the ports on the adapter, and Lz is a
logical label representing a logical PCI-e connection
to an I/O device at the other end of the PCI-e
cable plugged into that port (note that there may be
multiple Cx labels if the GX adapter doesn't plug
directly into the planar in the system in question).
This location code and DRC name will be generated
by system firmware for each PE on each GX adapter that
is installed in the system and that supports
direct-connect drawers (i.e. drawers without a PCI-E
switch in them). The location code and DRC
name will be generated regardless of whether or not a
PCI-E cable is attached to the GX adapter.
It is permissible to append additional labels beyond
the L label to create different location codes for
FRUs/devices downstream from the I/O device in the
drawer that is attached to the PCI-e cable. It is
not required that all subsequent labels be logical labels.</para>

<para>For GX cards whose ports connect to a PCI-E switch
in an I/O drawer via PCI-E cables, the location
code format has not yet been defined.</para>
</section>

<section xml:id="sec_virtual_scsi_device_location_codes">
<title>Virtual SCSI (vSCSI) Device Location Codes</title>

<para>The location code for a virtual SCSI (vSCSI)
device is formed by appending an L label to the location
code of the parent virtual IOA. The L label contains a
48 or 64 bit hexadecimal value that uniquely
identifies the virtualized SCSI device. A virtual
SCSI device attached to a virtual IOA at
U9119.MME.1085B17-V4-C5-T1 would have a location code of the form:
U9119.MME.1085B17-V4-C5-T1-L8100000000000000
Note that some old pSeries firmware may represent
the virtualized device identifier as
W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in
late 2008.</para>

<para>See <xref linkend="dbdoclet.50569341_32742" /> for a description of the
virtual IOA location code.</para>
</section>
<section xml:id="sec_virtual_scsi_device_location_codes">
<title>Virtual SCSI (vSCSI) Device Location Codes</title>

<para>The location code for a virtual SCSI (vSCSI)
device is formed by appending an L label to the location
code of the parent virtual IOA. The L label contains a
48 or 64 bit hexadecimal value that uniquely
identifies the virtualized SCSI device. A virtual
SCSI device attached to a virtual IOA at
U9119.MME.1085B17-V4-C5-T1 would have a location code of the form:
U9119.MME.1085B17-V4-C5-T1-L8100000000000000
Note that some old pSeries firmware may represent
the virtualized device identifier as
W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in
late 2008.</para>

<para>See <xref linkend="dbdoclet.50569341_32742" /> for a description of the
virtual IOA location code.</para>
</section>

<section xml:id="sec_virtual_fibre_channel_device_location_codes">
<title>Virtual Fibre Channel Device Location Codes</title>
<section xml:id="sec_virtual_fibre_channel_device_location_codes">
<title>Virtual Fibre Channel Device Location Codes</title>

<para>The location code for a virtual fibre channel device
is formed by appending the worldwide unique port
identifier (W label) and LUN (L label) to the location
code of the parent virtual IOA. The values of
the L and W labels are both in hexadecimal. A fibre
channel disk attached to a virtual IOA at
U9119.MME.1085B17-V4-C5-T1 would have a location
code of the form:</para>
<para>The location code for a virtual fibre channel device
is formed by appending the worldwide unique port
identifier (W label) and LUN (L label) to the location
code of the parent virtual IOA. The values of
the L and W labels are both in hexadecimal. A fibre
channel disk attached to a virtual IOA at
U9119.MME.1085B17-V4-C5-T1 would have a location
code of the form:</para>

<itemizedlist mark="none">
<listitem>
<para>U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000</para>
</listitem>
</itemizedlist>
<itemizedlist mark="none">
<listitem>
<para>U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000</para>
</listitem>
</itemizedlist>

<para>See <xref linkend="dbdoclet.50569341_32742" /> for a description of the
virtual IOA location code.</para>
</section>
<para>See <xref linkend="dbdoclet.50569341_32742" /> for a description of the
virtual IOA location code.</para>
</section>

<section xml:id="sec_nvme_device_logical_path_location_codes">
<title>NVMe Device Logical Path Location Codes</title>
<section xml:id="sec_nvme_device_logical_path_location_codes">
<title>NVMe Device Logical Path Location Codes</title>

<para>Non-volatile memory (NVM) devices that are
not mounted/docked on a backplane that supports
location code VPD will have location codes composed
of the location code of the controlling IOA
followed by a L label. The number value of L label
is a decimal value, and it is the unique NVMe
namespace identifier. An NVMe device controlled by
an IOA at U787A.001.1012345-P1-C5 would
have a location code of the form:</para>
<para>Non-volatile memory (NVM) devices that are
not mounted/docked on a backplane that supports
location code VPD will have location codes composed
of the location code of the controlling IOA
followed by a L label. The number value of L label
is a decimal value, and it is the unique NVMe
namespace identifier. An NVMe device controlled by
an IOA at U787A.001.1012345-P1-C5 would
have a location code of the form:</para>

<itemizedlist mark="none">
<listitem>
<para>U787A.001.1012345-P1-C5-L3</para>
</listitem>
</itemizedlist>
</section>
<itemizedlist mark="none">
<listitem>
<para>U787A.001.1012345-P1-C5-L3</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="sec_virtual_capi_function_location_codes">
<title>Virtual Coherent Accelerator (CAPI) Function Location Codes</title>
<section xml:id="sec_virtual_capi_function_location_codes">
<title>Virtual Coherent Accelerator (CAPI) Function Location Codes</title>

<para>The location code for a virtual coherent accelerator
(CA) function is formed by appending two S labels,
the first specifying the identifier of the physical
function and the second specifying the identifier of the
logical function, both in decimal, to the location code of
the physical CAPI adapter. A virtual CA
function associated with physical function 1 and logical
function 2 on the CAPI adapter at location
U78CA.001.1234567-P1-C4-C1 would have location code:</para>
<para>The location code for a virtual coherent accelerator
(CA) function is formed by appending two S labels,
the first specifying the identifier of the physical
function and the second specifying the identifier of the
logical function, both in decimal, to the location code of
the physical CAPI adapter. A virtual CA
function associated with physical function 1 and logical
function 2 on the CAPI adapter at location
U78CA.001.1234567-P1-C4-C1 would have location code:</para>

<itemizedlist mark="none">
<listitem>
<para>U78CA.001.1234567-P1-C4-C1-S1-S2</para>
</listitem>
</itemizedlist>
<itemizedlist mark="none">
<listitem>
<para>U78CA.001.1234567-P1-C4-C1-S1-S2</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>

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

-->
<chapter 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">

<title>Run-Time Abstration Services</title>
<?dbhtml stop-chunking?>

<xi:include href="sec_rtas_introduction.xml"/>
<xi:include href="sec_rtas_environment.xml"/>
<xi:include href="sec_rtas_call_defn.xml"/>

</chapter>

@ -15,7 +15,7 @@
limitations under the License.

-->
<appendix xmlns="http://docbook.org/ns/docbook"
<chapter 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"
@ -4165,4 +4165,4 @@
</section>

</section>
</appendix>
</chapter>

Before

Width:  |  Height:  |  Size: 66 KiB

After

Width:  |  Height:  |  Size: 66 KiB

Before

Width:  |  Height:  |  Size: 133 KiB

After

Width:  |  Height:  |  Size: 133 KiB

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 65 KiB

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 64 KiB

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 57 KiB

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

Before

Width:  |  Height:  |  Size: 2.9 KiB

After

Width:  |  Height:  |  Size: 2.9 KiB

Before

Width:  |  Height:  |  Size: 3.8 KiB

After

Width:  |  Height:  |  Size: 3.8 KiB

Before

Width:  |  Height:  |  Size: 7.0 KiB

After

Width:  |  Height:  |  Size: 7.0 KiB

Before

Width:  |  Height:  |  Size: 2.8 KiB

After

Width:  |  Height:  |  Size: 2.8 KiB

Before

Width:  |  Height:  |  Size: 3.8 KiB

After

Width:  |  Height:  |  Size: 3.8 KiB

Before

Width:  |  Height:  |  Size: 3.8 KiB

After

Width:  |  Height:  |  Size: 3.8 KiB

Before

Width:  |  Height:  |  Size: 3.6 KiB

After

Width:  |  Height:  |  Size: 3.6 KiB

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

Before

Width:  |  Height:  |  Size: 8.7 KiB

After

Width:  |  Height:  |  Size: 8.7 KiB

Before

Width:  |  Height:  |  Size: 9.2 KiB

After

Width:  |  Height:  |  Size: 9.2 KiB

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 50 KiB

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

Before

Width:  |  Height:  |  Size: 1012 B

After

Width:  |  Height:  |  Size: 1012 B

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 55 KiB

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

Before

Width:  |  Height:  |  Size: 9.8 KiB

After

Width:  |  Height:  |  Size: 9.8 KiB

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 37 KiB

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before

Width:  |  Height:  |  Size: 6.8 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

Before

Width:  |  Height:  |  Size: 5.3 KiB

After

Width:  |  Height:  |  Size: 5.3 KiB

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 35 KiB

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 56 KiB

Some files were not shown because too many files have changed in this diff Show More

Loading…
Cancel
Save