systemsoftware
/
Linux-Architecture-Reference
30
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Compare commits

base: systemsoftware:master
Branches Tags
systemsoftware:master
systemsoftware:papr_2.9+
systemsoftware:papr_2.7
systemsoftware:lopar-2.9
...
compare: systemsoftware:papr_2.9+
Branches Tags
systemsoftware:master
systemsoftware:papr_2.9+
systemsoftware:papr_2.7
systemsoftware:lopar-2.9

No commits in common. 'master' and 'papr_2.9+' have entirely different histories.
master ... papr_2.9+

165 changed files with 24359 additions and 15273 deletions
Show Stats

284
DeviceTree/app_bibliography.xml
Unescape Escape View File

@ -0,0 +1,284 @@
<?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:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dbdoclet.50569387_27251">
<?dbhtml stop-chunking?>
<title> Bibliography</title>
<para>This section lists documents which were referenced in this specification or which provide
additional information, and some useful information for obtaining these documents. Referenced
documents are listed below. When any of the following standards are superseded by an approved
revision, the revision shall apply.</para>
<orderedlist>
<!-- TODO: Uncomment documents needing referencing and comment out local document -->
<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>
<para><anchor xml:id="LoPAR.DeviceTree"
xreflabel="Linux on Power Architecture Reference: Device Tree"/><citetitle>
Linux on Power Architecture Reference: Device Tree</citetitle></para>
</listitem -->

<listitem>
<para><anchor xml:id="LoPAR.Error"
xreflabel="Linux on Power Architecture Reference: Error Recovery and Logging"/><citetitle>
Linux on Power Architecture Reference: Error Recovery and Logging</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.Virtualization"
xreflabel="Linux on Power Architecture Reference: Virtualization"/><citetitle>
Linux on Power Architecture Reference: Virtualization</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.RTAS"
xreflabel="Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)"/><citetitle>
Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)</citetitle></para>
</listitem>
<!-- End TODO list -->

<listitem>
<para><citetitle>Power ISA</citetitle><anchor xml:id="dbdoclet.50569387_99718"
xreflabel="Power ISA specification"/></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_45524"
xreflabel="IEEE Open Firmware standard"/>
<citetitle>IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware:
Core Requirements and Practices</citetitle></para>
<para>IEEE part number DS02683, ISBN 1-55937-426-8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_14175"
xreflabel="IEEE Open Firmware Errata specification"/>
<citetitle>Core Errata, IEEE P1275.7/D4</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_31707"
xreflabel="Open Firmware TFTP extensions"/>
<citetitle>Open Firmware Recommended Practice:OBP-TFTP
Extension</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27008"
xreflabel="Open Firmware Device Support Extensions specification"/>
<citetitle>Open Firmware Recommended Practice: Device
Support Extensions</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22451"
xreflabel="PCI Bus Binding to Open Firmware standard"/>
<citetitle>PCI Bus binding to: IEEE Std 1275-1994, Standard
for Boot (Initialization, Configuration) Firmware</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_40740"
xreflabel="Open Firmware Interrupt Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33384"
xreflabel="Open Firmware Forth Source and FCode Image Support specification"/>
<citetitle>Open Firmware: Recommended Practice - Forth Source
and FCode Image Support</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_67880"
xreflabel="Open Firmware Interrup Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33177"
xreflabel="Open Firmware TFTP Booting extensions"/>
<citetitle>Open Firmware: Recommended Practice - TFTP Booting
Extensions</citetitle>, Version 0.8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27351"
xreflabel="Open Firmware Interposition specification"/>
<citetitle>Open Firmware: Recommended Practice -
Interposition</citetitle>, Version 0.2</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22601"
xreflabel="MS-DOS Programmer's Reference specification"/>
<citetitle>MS-DOS Programmer's Reference</citetitle></para>
<para>Published by Microsoft</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_18190"
xreflabel="Win32 Executable File Format article"/>
<citetitle>Peering Inside the PE: A Tour of the Win32 Portable
Executable File Format</citetitle></para>
<para>Found in the March, 1994 issue of <citetitle> Microsoft Systems Journal</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_85757"
xreflabel="CD-ROM Volume and File Structure standard"/>
<citetitle> ISO-9660, Information processing -- Volume and
file structure of CD-ROM for information interchange</citetitle></para>
<para>Published by International Organization for Standardization</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38836"
xreflabel="System V Application Binary Interface, PowerPC Processor supplement"/>
<citetitle>System V Application Binary Interface, PowerPC
Processor Supplement</citetitle></para>
<para>By Sunsoft<citetitle></citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_11453"
xreflabel="Standard Generalized Markup Language (SGML) standard"/>
<citetitle>ISO Standard 8879:1986, Information Processing
-- Text and Office Systems -- Standard Generalized Markup Language (SGML)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38891"
xreflabel="Personal Computer Back Plane Bus standard"/>
<citetitle>IEEE 996, A Standard for an Extended Personal Computer
Back Plane Bus</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_65468"
xreflabel="PCI Local Bus specification"/>
<citetitle>PCI Local Bus Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_60429"
xreflabel="PCI-to-PCI Bridge Architecture specification"/>
<citetitle>PCI-to-PCI Bridge Architecture Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the
PCI SIG website for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_87046"
xreflabel="PCI Standard Hot-Plug Controller and Subsystem specification"/>
<citetitle>PCI Standard Hot-Plug Controller and Subsystem
Specification</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_26550"
xreflabel="PCI-X Protocol addendum"/>
<citetitle>PCI-X Protocol Addendum to the PCI Local Bus Specification </citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI-X related components or platforms. See the PCI SIG website for the most
current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_66784"
xreflabel="PCI Express Base specification"/>
<citetitle>PCI Express Base Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design PCI Express related components or platforms. See the PCI SIG website for
the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_28381"
xreflabel="PCI Express to PCI/PCI-X Bridge specification"/>
<citetitle>PCI Express to PCI/PCI-X Bridge Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express related components or platforms. See the PCI SIG website for the most current
version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_34114"
xreflabel="System Management BIOS reference"/>
<citetitle>System Management BIOS (SMBIOS) Reference
Specification</citetitle></para>
</listitem>
<!-- TODO: Are the following 3 items needed? -->
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><!-- anchor xml:id="dbdoclet.50569387_72648" xreflabel=""/ --><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_16481"
xreflabel="RS/6000 Product Topology Data System and Product Development guide"/>
<citetitle>IBM RS/6000&#174; Division, Product Topology Data System,
Product Development Guide</citetitle></para>
<para>Version 2.1</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_94229"
xreflabel="Single Root I/O Virtualization and Sharing specification"/>
<citetitle>Single Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_42471"
xreflabel="Multi-Root I/O Virtualization and Sharing specification"/>
<citetitle>Multi-Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the
most current version of this document.</para>
</listitem>
</orderedlist>

</appendix>

1290
DeviceTree/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

345
DeviceTree/bk_main.xml
Unescape Escape View File

@ -0,0 +1,345 @@
<?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"
status="draft"
xml:id="bk_main">

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

<title>Device Tree Bindings</title>
<subtitle>Linux on Power Architecture Reference</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_pre5</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 Device Tree Bindings on 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="http://tbd.openpowerfoundation.org">TBD</link>.</para>
</abstract>

<revhistory>
<!-- TODO: Update as new revisions created -->
<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 -- Appendix B (LoPAPR Binding) and Appendix C (PA Processor Binding).</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="../common/ch_LoPAR_preface.xml"/>

<!-- Chapter heading files -->
<xi:include href="ch_introduction.xml"/>
<xi:include href="ch_devtree_terms.xml"/>
<xi:include href="ch_devtree_system.xml"/>
<xi:include href="ch_devtree_pa.xml"/>


<!-- Document specific appendices -->
<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="../common/app_EOD.xml"/>

</book>

1532
LoPAR/app_pa_processor_binding.xml → DeviceTree/ch_devtree_pa.xml
View File

File diff suppressed because it is too large Load Diff

484
LoPAR/app_papr_binding.xml → DeviceTree/ch_devtree_system.xml
Unescape Escape View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
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.
@ -15,57 +15,13 @@
limitations under the License.

-->
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
<chapter xmlns="http://docbook.org/ns/docbook"
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>

@ -287,7 +243,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Installation Media:</para>
@ -991,7 +947,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>1</para>
@ -1625,7 +1581,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>C5</para>
@ -1710,156 +1666,6 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-uuid&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies a universally unique identifier for this partition.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string of data as described below, encoded as with
<emphasis role="bold">encode-string</emphasis></para>
<para>The Universally Unique IDentifier (UUID) option provides each partition with a
Universally Unique Identifier that is persisted by the platform across partition
reboots, reconfigurations, OS reinstalls, partition migration, hibernation etc.
The UUID is a 16 byte string of format fields and random bits as defined in
<xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>The random bits are generated in an implementation-dependent manner to
achieve a projected probability of collision of not greater than one in 2<superscript>60</superscript>.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20419">
<title>UUID Format</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte:Bit</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size (Bits)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>0:0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>0: Initial Version</para>
<para>1: Reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>0:1 thru 5:7</para>
</entry>
<entry>
<para>47</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Generation Method</para>
</entry>
<entry>
<para>6:0-3</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>0b0000 Never Used</para>
<para>0b0100 Random Generated</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>6:4 - 7:7</para>
</entry>
<entry>
<para>12</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Variant</para>
</entry>
<entry>
<para>8:0-1</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>0b10 DCE Variant UUID</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>8:2 - 15:7</para>
</entry>
<entry>
<para>62</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
</tbody>
</tgroup>
</table>


<para>For the GET_PARTNER_UUID subfunction (See <xref linkend="dbdoclet.50569348_62564"/>), the data is
represented as 16 bytes as described in <xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>For the ibm,partition-uuid property, the data is represented as a string of
hexadecimal characters, with hyphens added for readability.
Hexadecimal values a through f are lower case. An example of the string
representation of the UUID is 648a9ca6-1fb4-4f7e-9436-14d015f3dd74</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis></term>
<listitem>
@ -1978,7 +1784,7 @@
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the maximum VIOS level
that the client shall negotiate. See
<xref linkend="dbdoclet.50569379_75285" /> for the definition of the
<xref linkend="LoPAR.Virtualization" /> for the definition of the
values of this property.</para>
</listitem>
</varlistentry>
@ -2018,7 +1824,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0</para>
@ -2112,7 +1918,7 @@
<emphasis>property name</emphasis> to define that the OS may ignore
failures of Hot Plug power off and isolate operations during a DLPAR
remove operation. See also Note 2 in
<xref linkend="dbdoclet.50569342_17600" />.</para>
<xref linkend="LoPAR.Virtualization" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
@ -2155,7 +1961,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>ethernet_mac</para>
@ -2216,28 +2022,6 @@
<para>1 = Platform is operating in the Lightpath mode.</para>
</listitem>
</itemizedlist>

<para>
<emphasis role="bold">Implementation Notes:</emphasis>
</para>

<orderedlist>
<listitem>
<para>In the absence of this property, the determination of how the OS
is to behave is made by the platform presenting or not presenting FRU
Fault indicators to the OS see chapter
<xref linkend="dbdoclet.50569347_31867" />. In the case where there are
no FRUs owned by the partition, the OS will not observe any FRU Fault
indicators assigned, even when the platform is operating in the Lightpath
mode.</para>
</listitem>

<listitem>
<para>Presenting this property does not imply any relaxation of the
requirements specified in chapter
<xref linkend="dbdoclet.50569347_31867" />.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>

@ -2262,7 +2046,181 @@
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-uuid&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies a universally unique identifier for this partition.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string of data as described below, encoded as with
<emphasis role="bold">encode-string</emphasis></para>
<para>The Universally Unique IDentifier (UUID) option provides each partition with a
Universally Unique Identifier that is persisted by the platform across partition
reboots, reconfigurations, OS reinstalls, partition migration, hibernation etc.
The UUID is a 16 byte string of format fields and random bits as defined in
<xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>The random bits are generated in an implementation-dependent manner to
achieve a projected probability of collision of not greater than one in 2<superscript>60</superscript>.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20419">
<title>UUID Format</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte:Bit</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size (Bits)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>0:0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>0: Initial Version</para>
<para>1: Reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>0:1 thru 5:7</para>
</entry>
<entry>
<para>47</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Generation Method</para>
</entry>
<entry>
<para>6:0-3</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>0b0000 Never Used</para>
<para>0b0100 Random Generated</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>6:4 - 7:7</para>
</entry>
<entry>
<para>12</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Variant</para>
</entry>
<entry>
<para>8:0-1</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>0b10 DCE Variant UUID</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>8:2 - 15:7</para>
</entry>
<entry>
<para>62</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
</tbody>
</tgroup>
</table>


<para>For the GET_PARTNER_UUID subfunction (See <xref linkend="LoPAR.Virtualization"/>), the data is
represented as 16 bytes as described in <xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>For the ibm,partition-uuid property, the data is represented as a string of
hexadecimal characters, with hyphens added for readability.
Hexadecimal values a through f are lower case. An example of the string
representation of the UUID is 648a9ca6-1fb4-4f7e-9436-14d015f3dd74</para>
</listitem>
</varlistentry>
</variablelist>

<para>
<emphasis role="bold">Implementation Notes:</emphasis>
</para>


<orderedlist>
<listitem>
<para>In the absence of this property, the determination of how the OS
is to behave is made by the platform presenting or not presenting FRU
Fault indicators to the OS see chapter
<xref linkend="LoPAR.Error" />. In the case where there are
no FRUs owned by the partition, the OS will not observe any FRU Fault
indicators assigned, even when the platform is operating in the Lightpath
mode.</para>
</listitem>

<listitem>
<para>Presenting this property does not imply any relaxation of the
requirements spe3cified in chapter
<xref linkend="LoPAR.Error" />.</para>
</listitem>
</orderedlist>

</section>

<section xml:id="dbdoclet.50569368_10192">
@ -2327,7 +2285,7 @@
<emphasis role="bold"><literal>&#8220;ibm,client-architecture-support&#8221;</literal></emphasis>
and invoke that method with the
<!-- TODO: complete/correct this sentence -->
<emphasis role="bold"><literal>>ibm,???</literal></emphasis> compatible with the Real Base and Real Size constraints of the
<emphasis role="bold"><literal>>ibm,???</literal></emphasis> compatible (wording???) with the Real Base and Real Size constraints of the
kernel being loaded.</para>
</listitem>

@ -2544,7 +2502,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="18">
<para>Base</para>
@ -3265,7 +3223,7 @@
value indicates that the client supports the I/O Super Page
Option (Support of &gt;4K I/O pages) (Includes extensions to
H_MIGRATE_DMA for &gt;4K I/O pages and &gt;256 xlates).
See <xref linkend="dbdoclet.50569344_19308" />.</para>
See <xref linkend="LoPAR.Virtualization" />.</para>
<para>In the
<emphasis role="bold"><literal>ibm,architecture-vec-5</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, a non-zero value indicates
@ -3285,7 +3243,7 @@
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, this field represents the
implementation dependent number of xlates entries supported per
migration operation as: 256 * 2**N.
See <xref linkend="dbdoclet.50569344_19308" />.</para>
See <xref linkend="LoPAR.Virtualization" />.</para>
</entry>
</row>
<row>
@ -3300,7 +3258,7 @@
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, this field represents the
implementation dependent number of simultaneous migration
options supported as: 2**N.
See <xref linkend="dbdoclet.50569344_19308" />.</para>
See <xref linkend="LoPAR.Virtualization" />.</para>
</entry>
</row>
<row>
@ -3362,7 +3320,7 @@
<para>= the &#8220;Form value&#8221; of the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis>
properties. See <xref linkend="dbdoclet.50569346_35960" /> for further details.</para>
properties. See <xref linkend="LoPAR.Platform" /> for further details.</para>
</entry>
</row>
<row>
@ -3397,7 +3355,7 @@
<entry>
<para>Enable MTT Option</para>
<para>See
<xref linkend="dbdoclet.50569344_50921" />.</para>
<xref linkend="LoPAR.Virtualization" />.</para>
</entry>
</row>
<row>
@ -3447,7 +3405,7 @@
</entry>
<entry>
<para>Enable Hotplug Interrupts<?linebreak?>
See Hot Plug Events in <xref linkend="Hot_Plug_Events" />.</para>
See Hot Plug Events in <xref linkend="LoPAR.Error" />.</para>
</entry>
</row>
<row>
@ -4386,7 +4344,7 @@
<emphasis>token</emphasis>) for the defined indicators and the number of
indicators (
<emphasis>maxindex</emphasis>) for that token which are implemented (see
<xref linkend="dbdoclet.50569332_13537" />) on the platform.</para>
<xref linkend="LoPAR.RTAS" />) on the platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> The indicator indices for a given token are
numbered 0... maxindex-1.</para>
@ -4408,7 +4366,7 @@
<emphasis>token</emphasis>) for the defined sensors and the number of
sensors (
<emphasis>maxindex</emphasis>) for that token which are implemented (see
<xref linkend="dbdoclet.50569332_13537" />) on the platform.</para>
<xref linkend="LoPAR.RTAS" />) on the platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> The sensor indices for a given token are
numbered 0 ... maxindex-1.</para>
@ -4804,7 +4762,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="7">
<para>0</para>
@ -4931,7 +4889,7 @@
<para>
<emphasis>prop-encoded-array</emphasis>: Contains the description of the
registered kernel dump in the format described in
<xref linkend="dbdoclet.50569332_76933" />.</para>
<xref linkend="LoPAR.RTAS" />.</para>
</listitem>
</varlistentry>

@ -4947,7 +4905,7 @@
the first 3 inputs and the first 4 outputs (
<emphasis>Number Inputs</emphasis> is required to be 3 and the
<emphasis>Number Outputs</emphasis> is required to be 4), as defined in
<xref linkend="dbdoclet.50569332_80186" />.</para>
<xref linkend="LoPAR.RTAS" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Contains a 32 bit cell, with the
bits defined as follows:</para>
@ -4956,13 +4914,13 @@
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call checks the
<emphasis>Number Outputs</emphasis> and the implements the 5th output (
<emphasis>Number Outputs</emphasis> of 5), as defined by
<xref linkend="dbdoclet.50569332_80186" />.</para>
<xref linkend="LoPAR.RTAS" />.</para>
<para>Bit 31: When a value of 1, the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call implements the
first 3 inputs and the first 4 outputs (
<emphasis>Number Inputs</emphasis> of 3 and the
<emphasis>Number Outputs</emphasis> of 4), as defined in
<xref linkend="dbdoclet.50569332_80186" />. This bit is always required
<xref linkend="LoPAR.RTAS" />. This bit is always required
to be a value of 1 when this property is implemented.</para>
</listitem>
</varlistentry>
@ -5033,7 +4991,7 @@
<para><emphasis>property-name</emphasis> indicating that the platform supports
extended
<emphasis>ibm,os-term</emphasis> behavior as described in
<xref linkend="dbdoclet.50569332_42118" />.</para>
<xref linkend="LoPAR.RTAS" />.</para>
<para><emphasis>prop-encoded-array</emphasis>: encode-null</para>
</listitem>
</varlistentry>
@ -5046,8 +5004,8 @@

<para>This section defines the property names associated with the various
RTAS functions defined by
<xref linkend="dbdoclet.50569332_20008" />.
<xref linkend="dbdoclet.50569332_20008" /> should be used as the reference
<xref linkend="LoPAR.RTAS" />.
<xref linkend="LoPAR.RTAS" /> should be used as the reference
for RTAS Functions currently implemented. Each RTAS function that a
platform implements shall
be represented by its own function property,
@ -5074,7 +5032,7 @@
<emphasis>rtas-call</emphasis> interface (see below), invokes the named
RTAS function. If a RTAS function is not implemented, there will not be a
property corresponding to that function name. See the
<xref linkend="dbdoclet.50569332_13537" /> for more information about RTAS
<xref linkend="LoPAR.RTAS" /> for more information about RTAS
functions.</para>
</listitem>
</varlistentry>
@ -5500,7 +5458,7 @@
<para>The first specification shall specify the configured address and
size of this PHB&#8217;s I/O Space. (I/O Space is shown as
&#8220;BIOn&#8221; to &#8220;TIOn&#8221; in
<xref linkend="dbdoclet.50569328_Address-Map" />.) The
<xref linkend="LoPAR.Platform" /> "Address Map" section.) The
second specification shall specify the configured address and size of
this PHB&#8217;s Memory Space. (Memory Space is shown as
&#8220;BPMn&#8221; to &#8220;TPMn&#8221; in the Common Hardware Reference
@ -5593,7 +5551,7 @@
<para><emphasis>prop-encoded-array</emphasis>: Integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This property, when present (for example, see Requirement
<xref linkend="dbdoclet.50569335_65475" />), indicates the maximum DMA
<xref linkend="LoPAR.Platform" />), indicates the maximum DMA
Read completion latency for IOAs under this PHB, in microseconds. For
plug-in adapters, the latency value does not include latency of any
additional PCI fabric (for example, PCI Express switches) on the plug-in
@ -5860,7 +5818,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>storage-system-io</para>
@ -5972,7 +5930,7 @@
as a token for an additional RTAS call or an architectural level of an
extended interface. The value of one indicates that only a single
extension is implemented as specified by the second integer in the list.
<xref linkend="dbdoclet.50569332_25585" /> provides the definition of the
<xref linkend="LoPAR.RTAS" /> provides the definition of the
subsequent integers as defined for the LoPAR level of the DDW
option.</para>
</listitem>
@ -6062,7 +6020,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0</para>
@ -6335,7 +6293,7 @@
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Name</para>
@ -7450,7 +7408,7 @@
<listitem>
<para><emphasis>property name</emphasis> to provide Vital Product Data (VPD)
information as defined in
<xref linkend="dbdoclet.50569341_29745" />.</para>
<xref linkend="LoPAR.Platform" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: the concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of one or more pairs of elements, the first
@ -7829,7 +7787,7 @@

</section>

<section xml:id="sec_papr_bindings_hot_plug_events">
<section>
<title>hot-plug-events</title>

<para>The presence of the node indicates that all or some of the function
@ -8329,7 +8287,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>
@ -8365,7 +8323,7 @@
</tgroup>
</table>
<para>See
<xref linkend="dbdoclet.50569352_15379" /> for further detail on this
<xref linkend="LoPAR.Error" /> for further detail on this
virtual device.</para>
</listitem>
</varlistentry>
@ -8410,7 +8368,7 @@
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property value. The following
properties are the minimum required, optional support such as dynamic
reconfiguration will add properties per requirements called out in the
<xref linkend="dbdoclet.50569342_82208" />.</para>
<xref linkend="LoPAR.Virtualization" />.</para>

<variablelist>
<varlistentry>
@ -10320,7 +10278,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>100</para>
@ -10408,7 +10366,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="3" valign="middle">
<para>&#160;</para>
@ -10641,7 +10599,7 @@ where:
power management related information shall be resident in the OF device
tree prior to the transfer phase of software operation (see the
definition of transfer phase in
<xref linkend="dbdoclet.50569327_31987" />). Dummy devices shall be
<xref linkend="LoPAR.Platform" />). Dummy devices shall be
placed in the device tree for all standard I/O bus connectors which are
not in use to provide a node to assign the slot-names, power-domains, and
power-sources properties.</para>
@ -10753,7 +10711,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Version</para>
@ -10832,7 +10790,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Block_type</para>
@ -10891,7 +10849,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Block_type</para>
@ -10981,7 +10939,7 @@ where:
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Block_type</para>
@ -12239,4 +12197,4 @@ else

</section>

</appendix>
</chapter>

121
LoPAR/sec_papr_binding_terms.xml → DeviceTree/ch_devtree_terms.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,21 +13,21 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

xml:id="ch_devtree_terms">
<title>Terms</title>

<para>This standard uses technical terms as they are defined in the
IEEE Std 1275-1994 Standard and other
documents cited in &#8220;References&#8221;, plus the following
terms:</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">ARP</emphasis></term>
@ -73,9 +73,21 @@
</varlistentry>

<varlistentry>
<term><emphasis role="bold">ELF</emphasis></term>
<term><emphasis role="bold">effective address</emphasis></term>
<listitem>
<para>The 64- or 32-bit address computed by the processor
when executing a Storage Access or Branch instruction, or when fetching the
next sequential instruction. If address translation is disabled, the real
address is the same as the effective address. If address translation is
enabled, the real address is determined by, but not necessarily identical
to, the effective address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">ELF Executable and Linking Format</emphasis></term>
<listitem>
<para>Executable and Linking Format. A binary object file format defined by
<para>A binary object file format defined by
<xref linkend="dbdoclet.50569387_38836" /> that is used to represent client
programs in OF for PA.</para>
</listitem>
@ -85,7 +97,7 @@
<term><emphasis role="bold">FDISK</emphasis></term>
<listitem>
<para>Refers to the boot-record and partition table format used by
MS-DOS, as defined in
MS-DOS, as defined in
<xref linkend="dbdoclet.50569387_22601" />.</para>
</listitem>
</varlistentry>
@ -140,6 +152,16 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">linkage area</emphasis></term>
<listitem>
<para>An area within the stack that is reserved for saving
certain registers across procedure calls in PA run-time models. This area
is reserved by the caller and is allocated above the current stack pointer
(<literal>%r1</literal>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">NVRAM</emphasis></term>
<listitem>
@ -152,8 +174,8 @@
<varlistentry>
<term><emphasis role="bold">Open Firmware (OF)</emphasis></term>
<listitem>
<para>The firmware architecture defined by
<xref linkend="dbdoclet.50569387_45524" /> and
<para>The firmware architecture defined by
<xref linkend="dbdoclet.50569387_45524" /> and
<xref linkend="dbdoclet.50569387_14175" />, or, when used as an adjective,
a software component compliant with the core specification and
errata.</para>
@ -171,11 +193,27 @@
<varlistentry>
<term><emphasis role="bold">PE</emphasis></term>
<listitem>
<para>Portable Executable. A binary object file format defined by
<para>Portable Executable. A binary object file format defined by
<xref linkend="dbdoclet.50569387_18190" />.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">procedure descriptor</emphasis></term>
<listitem>
<para>A data structure used by some PA run-time models
to represent a C &#8220;pointer to procedure&#8221;. The first word of this
structure contains the actual address of the procedure.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">processor bus</emphasis></term>
<listitem>
<para>The bus that connects the CPU chip to the system.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">PROM</emphasis></term>
<listitem>
@ -183,6 +221,14 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">real address</emphasis></term>
<listitem>
<para>An address that the processor presents on the processor
bus.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">real-mode</emphasis></term>
<listitem>
@ -207,6 +253,17 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">segmented address translation</emphasis></term>
<listitem>
<para>The process whereby an Effective Address (EA) is translated into a
Virtual Address (VA) and the virtual address is translated into a Real
Address (RA). (see
<xref linkend="dbdoclet.50569374_41703" />and Book III of
<xref linkend="dbdoclet.50569387_99718" />for more detail.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">suspend</emphasis></term>
<listitem>
@ -216,6 +273,16 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">Table of Contents (TOC)</emphasis></term>
<listitem>
<para>A data structure used by some PA run-time models that is used for
access to global variables and for inter-module linkage. When a TOC is
used,
<emphasis>%r2</emphasis> contains its base address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">TFTP</emphasis></term>
<listitem>
@ -230,6 +297,26 @@
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">Virtual Address</emphasis></term>
<listitem>
<para>In IEEE 1275 parlance, the address that a program uses to access
a memory location or
memory-mapped device register. Depending on the presence or absence of
memory mapping hardware in the system, and whether or not that mapping
hardware is enabled, a virtual address may or may not be the same as the
physical (real) address that appears on an external bus. The IEEE 1275
definition of &#8220;virtual address&#8221; corresponds to The PA's
definition of &#8220;effective address.&#8221; Except as noted, this
document uses the IEEE 1275 definition of virtual address.</para>
<para>In PA parlance, an internal address within the PA address
translation mechanism, used
as in intermediate term in the translation of an effective address to the
corresponding real address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">virtual-mode</emphasis></term>
<listitem>
@ -239,5 +326,5 @@
</listitem>
</varlistentry>
</variablelist>

</section>
</chapter>

97
DeviceTree/ch_introduction.xml
Unescape Escape View File

@ -0,0 +1,97 @@
<?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:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_introduction">
<title>Introduction</title>
<para>This document specifies the application of OF to an LoPAR 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 an
LoPAR System. This appendix establishes such additional requirements
pertaining to the platform and the support required by OF.</para>
<para>This document also specifies the application of OF to a PA Processor
(which covers all PowerPC processors and their successors), 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.
<xref linkend="dbdoclet.50569374_59715" />
establishes such additional requirements pertaining to the
processor and the support required by OF.</para>

<para>This document further 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</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>
<title>Processor Architecture Requirements</title>

<para><xref linkend="dbdoclet.50569374_59715" /> 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>
</chapter>

0
LoPAR/figures/PAPR-60.gif → DeviceTree/figures/PAPR-60.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

0
LoPAR/figures/PAPR-61.gif → DeviceTree/figures/PAPR-61.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

0
LoPAR/figures/PAPR-62.gif → DeviceTree/figures/PAPR-62.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

0
LoPAR/figures/PAPR-64.gif → DeviceTree/figures/PAPR-64.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

148
DeviceTree/pom.xml
Unescape Escape View File

@ -0,0 +1,148 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>

<groupId>org.openpowerfoundation.docs</groupId>
<artifactId>workgroup-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>

<!-- TODO: Rename the artifactID field to some appropriate for your new document -->
<artifactId>LoPAR-DeviceTree</artifactId>

<packaging>jar</packaging>
<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>LoPAR-DeviceTree</name>

<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name></release.path.name>
<comments.enabled>0</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>

<groupId>org.openpowerfoundation.docs</groupId>

<artifactId>openpowerdocs-maven-plugin</artifactId>
<!-- version set in ../pom.xml -->
<executions>
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>${comments.enabled}</enableDisqus>
<disqusShortname>LoPAR-DeviceTree</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
book/appendix nop
book/chapter nop
chapter toc,title
chapter/section nop
section toc
part toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>1</sectionAutolabel>
<tocSectionDepth>3</tocSectionDepth>
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>

<!-- TODO: Rename the webhelpDirname field to the new directory for new document -->
<webhelpDirname>LoPAR_DeviceTree</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>LoPAR_DeviceTree</pdfFilenameBase>

<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
Consult with the Work Group Chair or a Technical Steering Committee member if you have
questions about which value to select.
If no value is provided below, the document will default to "Work Group Notes".-->
<workProduct>workgroupNotes</workProduct>
<!-- workProduct>workgroupSpecification</workProduct -->
<!-- workProduct>candidateStandard</workProduct -->
<!-- workProduct>openpowerStandard</workProduct -->

<!-- TODO: Set the appropriate security policy for the document. For documents
which are not "public" this will affect the document title page and
create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

public = this document may be shared outside the
foundation and thus this setting must be
used only when completely sure it allowed
foundationConfidential = this document may be shared freely with
OpenPOWER Foundation members but may not be
shared publicly
workgroupConfidential = this document may only be shared within the
work group and should not be shared with
other Foundation members or the public

The appropriate starting security for a new document is "workgroupConfidential". -->
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->

<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

published = this document has completed all reviews and has
been published
draft = this document is actively being updated and has
not yet been reviewed
review = this document is presently being reviewed

The appropriate starting security for a new document is "draft". -->
<!-- documentStatus>draft</documentStatus -->
<documentStatus>review</documentStatus>
<!-- documentStatus>publish</documentStatus -->

</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
<!-- TODO: If you desire, you may change the following filename to something more appropriate for the new document -->
bk_main.xml
</includes>

<!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
<!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
<includeCoverLogo>1</includeCoverLogo>
<coverUrl>www.openpowerfoundation.org</coverUrl>
</configuration>
</plugin>
</plugins>
</build>
</project>

284
Error Handling/app_bibliography.xml
Unescape Escape View File

@ -0,0 +1,284 @@
<?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:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dbdoclet.50569387_27251">
<?dbhtml stop-chunking?>
<title> Bibliography</title>
<para>This section lists documents which were referenced in this specification or which provide
additional information, and some useful information for obtaining these documents. Referenced
documents are listed below. When any of the following standards are superseded by an approved
revision, the revision shall apply.</para>
<orderedlist>
<!-- TODO: Uncomment documents needing referencing and comment out local document -->
<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>
<para><anchor xml:id="LoPAR.DeviceTree"
xreflabel="Linux on Power Architecture Reference: Device Tree"/><citetitle>
Linux on Power Architecture Reference: Device Tree</citetitle></para>
</listitem>

<!-- listitem>
<para><anchor xml:id="LoPAR.Error"
xreflabel="Linux on Power Architecture Reference: Error Recovery and Logging"/><citetitle>
Linux on Power Architecture Reference: Error Recovery and Logging</citetitle></para>
</listitem -->

<listitem>
<para><anchor xml:id="LoPAR.Virtualization"
xreflabel="Linux on Power Architecture Reference: Virtualization"/><citetitle>
Linux on Power Architecture Reference: Virtualization</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.RTAS"
xreflabel="Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)"/><citetitle>
Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)</citetitle></para>
</listitem>
<!-- End TODO list -->

<listitem>
<para><citetitle>Power ISA</citetitle><anchor xml:id="dbdoclet.50569387_99718"
xreflabel="Power ISA specification"/></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_45524"
xreflabel="IEEE Open Firmware standard"/>
<citetitle>IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware:
Core Requirements and Practices</citetitle></para>
<para>IEEE part number DS02683, ISBN 1-55937-426-8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_14175"
xreflabel="IEEE Open Firmware Errata specification"/>
<citetitle>Core Errata, IEEE P1275.7/D4</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_31707"
xreflabel="Open Firmware TFTP extensions"/>
<citetitle>Open Firmware Recommended Practice:OBP-TFTP
Extension</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27008"
xreflabel="Open Firmware Device Support Extensions specification"/>
<citetitle>Open Firmware Recommended Practice: Device
Support Extensions</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22451"
xreflabel="PCI Bus Binding to Open Firmware standard"/>
<citetitle>PCI Bus binding to: IEEE Std 1275-1994, Standard
for Boot (Initialization, Configuration) Firmware</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_40740"
xreflabel="Open Firmware Interrupt Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33384"
xreflabel="Open Firmware Forth Source and FCode Image Support specification"/>
<citetitle>Open Firmware: Recommended Practice - Forth Source
and FCode Image Support</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_67880"
xreflabel="Open Firmware Interrup Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33177"
xreflabel="Open Firmware TFTP Booting extensions"/>
<citetitle>Open Firmware: Recommended Practice - TFTP Booting
Extensions</citetitle>, Version 0.8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27351"
xreflabel="Open Firmware Interposition specification"/>
<citetitle>Open Firmware: Recommended Practice -
Interposition</citetitle>, Version 0.2</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22601"
xreflabel="MS-DOS Programmer's Reference specification"/>
<citetitle>MS-DOS Programmer's Reference</citetitle></para>
<para>Published by Microsoft</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_18190"
xreflabel="Win32 Executable File Format article"/>
<citetitle>Peering Inside the PE: A Tour of the Win32 Portable
Executable File Format</citetitle></para>
<para>Found in the March, 1994 issue of <citetitle> Microsoft Systems Journal</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_85757"
xreflabel="CD-ROM Volume and File Structure standard"/>
<citetitle> ISO-9660, Information processing -- Volume and
file structure of CD-ROM for information interchange</citetitle></para>
<para>Published by International Organization for Standardization</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38836"
xreflabel="System V Application Binary Interface, PowerPC Processor supplement"/>
<citetitle>System V Application Binary Interface, PowerPC
Processor Supplement</citetitle></para>
<para>By Sunsoft<citetitle></citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_11453"
xreflabel="Standard Generalized Markup Language (SGML) standard"/>
<citetitle>ISO Standard 8879:1986, Information Processing
-- Text and Office Systems -- Standard Generalized Markup Language (SGML)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38891"
xreflabel="Personal Computer Back Plane Bus standard"/>
<citetitle>IEEE 996, A Standard for an Extended Personal Computer
Back Plane Bus</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_65468"
xreflabel="PCI Local Bus specification"/>
<citetitle>PCI Local Bus Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_60429"
xreflabel="PCI-to-PCI Bridge Architecture specification"/>
<citetitle>PCI-to-PCI Bridge Architecture Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the
PCI SIG website for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_87046"
xreflabel="PCI Standard Hot-Plug Controller and Subsystem specification"/>
<citetitle>PCI Standard Hot-Plug Controller and Subsystem
Specification</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_26550"
xreflabel="PCI-X Protocol addendum"/>
<citetitle>PCI-X Protocol Addendum to the PCI Local Bus Specification </citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI-X related components or platforms. See the PCI SIG website for the most
current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_66784"
xreflabel="PCI Express Base specification"/>
<citetitle>PCI Express Base Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design PCI Express related components or platforms. See the PCI SIG website for
the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_28381"
xreflabel="PCI Express to PCI/PCI-X Bridge specification"/>
<citetitle>PCI Express to PCI/PCI-X Bridge Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express related components or platforms. See the PCI SIG website for the most current
version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_34114"
xreflabel="System Management BIOS reference"/>
<citetitle>System Management BIOS (SMBIOS) Reference
Specification</citetitle></para>
</listitem>
<!-- TODO: Are the following 3 items needed? -->
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><!-- anchor xml:id="dbdoclet.50569387_72648" xreflabel=""/ --><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_16481"
xreflabel="RS/6000 Product Topology Data System and Product Development guide"/>
<citetitle>IBM RS/6000&#174; Division, Product Topology Data System,
Product Development Guide</citetitle></para>
<para>Version 2.1</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_94229"
xreflabel="Single Root I/O Virtualization and Sharing specification"/>
<citetitle>Single Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_42471"
xreflabel="Multi-Root I/O Virtualization and Sharing specification"/>
<citetitle>Multi-Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the
most current version of this document.</para>
</listitem>
</orderedlist>

</appendix>

7
LoPAR/app_capi_error_handling.xml → Error Handling/app_capi_error_handling.xml
Unescape Escape View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
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.
@ -16,10 +16,7 @@

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

51
LoPAR/app_fault_v_errorlog.xml → Error Handling/app_fault_v_errorlog.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,16 +13,13 @@
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="dbdoclet.50569385_36278">
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569385_36278">
<title>
When to use: Fault vs. Error Log Indicators (Lightpath Mode)</title>
<para>This appendix gives
<para>This appendix gives
<emphasis>highly</emphasis> recommended Service Indicator activation models
for typical system issues, when the Lightpath mode is implemented. The
purpose of this appendix is to get consistency across platforms, and to
@ -31,18 +28,18 @@
that are involved, specifically related to the different types of physical
layouts (for example: deskside, blade and blade chassis, rack-mounted and
particularly high end racks).</para>
<para>This appendix does
<para>This appendix does
<emphasis>not</emphasis> change the architectural requirements specified in
other parts of this document, nor the requirement for implementations to
support those requirements. If there are any inconsistencies between this
appendix and the requirements in the rest of this document, the requirements
take precedence over this appendix. It is very important, therefore, that
designers understand the requirements in this architecture, and more
specifically, those in
specifically, those in
<xref linkend="dbdoclet.50569347_86824" />.</para>
<para><xref linkend="dbdoclet.50569385_72358" /> gives the recommended models. The
general model, though, is still dictated by the following requirement, copied
here from the <xref linkend="dbdoclet.50569347_86824" />:</para>
here from the <xref linkend="LoPAR.Platform" />:</para>
<informalfigure>
<mediaobject>
<imageobject role="html">
@ -57,7 +54,7 @@

<table frame="all" pgwide="1" xml:id="dbdoclet.50569385_72358">
<title>Service Indicator Activation Models for Typical System
Issues (Lightpath Mode)
Issues (Lightpath Mode)
<emphasis></emphasis></title>
<tgroup cols="7">
<colspec colname="c1" colwidth="15*" />
@ -82,8 +79,8 @@
<entry nameend="c4" namest="c3">
<para>
<emphasis role="bold">Indicator activation?
<emphasis><?linebreak?>(see notes
<xref linkend="dbdoclet.50569385_14395" xrefstyle="select: nopage" />,
<emphasis><?linebreak?>(see notes
<xref linkend="dbdoclet.50569385_14395" xrefstyle="select: nopage" />,
<xref linkend="dbdoclet.50569385_43948" xrefstyle="select: nopage" />)</emphasis></emphasis>
</para>
</entry>
@ -107,7 +104,7 @@
<row>
<entry>
<para>FRU Fault indicator?<?linebreak?>(see notes
<xref linkend="dbdoclet.50569385_57037" xrefstyle="select: nopage" />,
<xref linkend="dbdoclet.50569385_57037" xrefstyle="select: nopage" />,
<xref linkend="dbdoclet.50569385_69283" xrefstyle="select: nopage" />)</para>
</entry>
<entry>
@ -116,7 +113,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>All</para>
@ -748,7 +745,7 @@
<para>no</para>
</entry>
<entry>
<para>See also Requirement
<para>See also Requirement
<xref linkend="dbdoclet.50569347_86824" /></para>
</entry>
</row>
@ -850,13 +847,13 @@
<para>
<emphasis role="bold">Notes:</emphasis>
</para>

<orderedlist>
<orderedlist>
<listitem xml:id="dbdoclet.50569385_14395">
<para>Never activate both a
Fault indicator and an Error Log indicator for the same problem. See also
Requirement
<xref linkend="dbdoclet.50569347_86824" />, referenced immediately above
Requirement
<xref linkend="dbdoclet.50569347_86824" />, referenced immediately above
<xref linkend="dbdoclet.50569385_72358" />.</para>
</listitem>

@ -870,11 +867,11 @@
<listitem xml:id="dbdoclet.50569385_57037">
<para>Enclosure Fault
indicators and above are only roll-up indicators and are never activated
without a FRU Fault indicator being activated. Therefore the column in
without a FRU Fault indicator being activated. Therefore the column in
<xref linkend="dbdoclet.50569385_72358" />indicates a FRU Fault indicator.
That is, if no FRU Fault indicator exists for the problem, then the Error Log
indicator is used instead (per Requirement
<xref linkend="dbdoclet.50569347_86824" />, referenced immediately above
indicator is used instead (per Requirement
<xref linkend="dbdoclet.50569347_86824" />, referenced immediately above
<xref linkend="dbdoclet.50569385_72358" />).</para>
</listitem>

@ -883,11 +880,11 @@
Error Log indicator (previously known as the System Information (Attention)
indicator) and Fault indicators are regulated by the following requirements,
among others:</para>
<itemizedlist>
<itemizedlist>
<listitem><para><xref linkend="dbdoclet.50569347_17215"/></para></listitem>

<listitem><para><xref linkend="dbdoclet.50569347_38463"/></para></listitem>
</itemizedlist>
</itemizedlist>
</listitem>
</orderedlist>

1290
Error Handling/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

1776
LoPAR/ch_service_indicators.xml → Error Handling/app_service_indicators.xml
View File

File diff suppressed because it is too large Load Diff

348
Error Handling/bk_main.xml
Unescape Escape View File

@ -0,0 +1,348 @@
<?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"
status="draft"
xml:id="bk_main">

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

<title>Error Handling</title>
<subtitle>Linux on Power Architecture Reference</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_pre5</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

<legalnotice role="apache2">

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

<!-- TODO: Update the mailing list information in second paragraph. -->
<abstract>
<para>The purpose of this document is to provide firmware and software
architectural details associated with Error Recovery and Logging on 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="http://tbd.openpowerfoundation.org">TBD</link>.</para>
</abstract>

<revhistory>
<!-- TODO: Update as new revisions created -->
<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 -- Section 7.3.3 ([RTAS] Error and Event Reporting), Chapter 10 (Error and
Event Notification), Sections 1-3 of Chapter 16 (Service Indicators), and
Appendix L (When to use: Fault vs. Error Log Indicators).</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="../common/ch_LoPAR_preface.xml"/>

<!-- Chapter heading files -->
<xi:include href="ch_notifications.xml"/>
<xi:include href="ch_rtas_error_classes.xml"/>
<xi:include href="ch_rtas_error_reporting.xml"/>
<xi:include href="ch_error_codes.xml"/>

<!-- Document specific appendices -->
<xi:include href="app_service_indicators.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="../common/app_EOD.xml"/>

</book>

152
LoPAR/sec_error_codes.xml → Error Handling/ch_error_codes.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,23 +13,23 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<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"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
xml:id="ch_error_codes">

<title>Error Codes</title>

<section xml:id="dbdoclet.50569337_63826">
<title>Displaying Codes on the Standard Operator Panels</title>

<variablelist>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">Platform Implementation:</emphasis> Platforms must display
@ -38,9 +38,9 @@
first line.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">Platform Implementation:</emphasis> Platforms must display
@ -49,9 +49,9 @@
display (if available).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_63826"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">Platform Implementation:</emphasis> When a platform displays
@ -61,17 +61,17 @@
available).</para>
</listitem>
</varlistentry>

</variablelist>

<para>The following describes in more detail the standard platform usage
of operator panel LEDs or LCDs for the display of firmware progress and
error codes.</para>

<itemizedlist>
<listitem>

<para><emphasis role="bold">Progress codes: </emphasis>Progress codes
<para><emphasis role="bold">Progress codes: </emphasis>Progress codes
from the system firmware and
service processor firmware are 4 hex digits in the range from 0x8000
through 0xFFFF. Codes are displayed in the 4 character positions of a 1x4
@ -79,12 +79,12 @@
progress codes are displayed on top of (overlaying) the previous one. If
the system &#8220;hangs&#8221;, the last displayed progress code is left
on the display.</para>

</listitem>
<listitem>

<para><emphasis role="bold">Error codes: </emphasis>Error codes are 8
hex digits, as defined in
<para><emphasis role="bold">Error codes: </emphasis>Error codes are 8
hex digits, as defined in
<xref linkend="dbdoclet.50569337_36534"/>. These codes are displayed by
either boot ROM Power On Self Test (POST) or the service processor. If a
critical error is detected which prevents a successful boot or results in
@ -97,11 +97,11 @@
normally or in a degraded mode, the associated error codes are not
displayed, but are reported to the OS via the POST error log and the RTAS
<emphasis>event-scan</emphasis> service.</para>

</listitem>
<listitem>

<para><emphasis role="bold">Location Codes: </emphasis>Location codes
<para><emphasis role="bold">Location Codes: </emphasis>Location codes
describe the physical location of
the most probable failing part associated with an error code. When an
error code is displayed on the first line of a 2x16 LCD, the location
@ -110,51 +110,51 @@
system is reset or powered down. Location codes for POST errors are also
displayed on any system console (graphic or tty), on the next line below
the error code.</para>

</listitem>
</itemizedlist>

</section>

<section xml:id="dbdoclet.50569337_36534">
<title>Firmware Error Codes</title>

<para>The error code is an 8-character (4-byte) hexadecimal code produced
by firmware to identify the potential failing function or FRU in a
system. It consists of 5 source code characters and 3 reason code
characters. Individual characters within the error code have specific
field definitions, as defined in the following tables.</para>

<variablelist>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_36534"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_36534"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">Platform Implementation:</emphasis> To indicate the occurrence
of a critical platform error, platforms must display (either on an
operator panel or console) an 8-digit hex error code as defined in
<xref linkend="dbdoclet.50569337_58681"/> and
operator panel or console) an 8-digit hex error code as defined in
<xref linkend="dbdoclet.50569337_58681"/> and
<xref linkend="dbdoclet.50569337_51582"/>.</para>
</listitem>
</varlistentry>

</variablelist>


<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_58681">
<title>Service Reference Code (SRC) Field Layout</title>
<?dbhtml table-width="50%" ?>
<?dbfo table-width="50%" ?>
<tgroup cols="8">
<colspec colname="c1" colwidth="12*" align="center" />
<colspec colname="c2" colwidth="12*" align="center" />
<colspec colname="c3" colwidth="12*" align="center" />
<colspec colname="c4" colwidth="12*" align="center" />
<colspec colname="c5" colwidth="12*" align="center" />
<colspec colname="c6" colwidth="12*" align="center" />
<colspec colname="c7" colwidth="12*" align="center" />
<colspec colname="c8" colwidth="12*" align="center" />
<colspec colname="c1" colwidth="12*" />
<colspec colname="c2" colwidth="12*" />
<colspec colname="c3" colwidth="12*" />
<colspec colname="c4" colwidth="12*" />
<colspec colname="c5" colwidth="12*" />
<colspec colname="c6" colwidth="12*" />
<colspec colname="c7" colwidth="12*" />
<colspec colname="c8" colwidth="12*" />
<thead>
<row>
<entry nameend="c5" namest="c1">
@ -169,7 +169,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry nameend="c2" namest="c1">
<para>
@ -228,7 +228,7 @@
<?dbhtml table-width="80%" ?>
<?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c1" colwidth="15*" />
<colspec colname="c2" colwidth="85*" />
<thead>
<row>
@ -237,14 +237,14 @@
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>S1</para>
@ -269,10 +269,10 @@
<para>S2</para>
</entry>
<entry>
<para>Where applicable, use the lower nibble of the
<para>Where applicable, use the lower nibble of the
<emphasis>
<xref linkend="dbdoclet.50569387_65468"/>
</emphasis> base class code for the IOA definition (see
</emphasis> base class code for the IOA definition (see
<xref linkend="dbdoclet.50569337_10405"/>). Only 00 to 0C are
currently defined in Revision 2.1, therefore the high nibble is
always zero. (There is a potential exposure that the high
@ -280,7 +280,7 @@
13 base classes defined which include every device class, with
3 remaining characters for future extension by the PCI SIG.
Therefore the exposure is in the far future.) For non-PCI
devices, use base class 0 to extend the definition (see
devices, use base class 0 to extend the definition (see
<xref linkend="dbdoclet.50569337_69141"/>).</para>
</entry>
</row>
@ -289,13 +289,13 @@
<para>S3-S4</para>
</entry>
<entry>
<para>Where applicable, use the
<para>Where applicable, use the
<emphasis>
<xref linkend="dbdoclet.50569387_65468"/>
</emphasis> subclass code for IOA definition (see
</emphasis> subclass code for IOA definition (see
<xref linkend="dbdoclet.50569337_10405"/>). Also, extend the
definition to include non-PCI devices where it is not fully
utilized by PCI specification (see
utilized by PCI specification (see
<xref linkend="dbdoclet.50569337_69141"/>).</para>
</entry>
</row>
@ -349,8 +349,8 @@
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
@ -365,19 +365,19 @@
<emphasis role="bold">PCI Sub-ClassS3-S4</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="2">
<para>0</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Devices that were built before the class code field was
defined</para>
</entry>
@ -403,7 +403,7 @@
<entry morerows="6">
<para>1</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Mass storage controller.</para>
</entry>
</row>
@ -461,7 +461,7 @@
<entry morerows="5">
<para>2</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Network controller.</para>
</entry>
</row>
@ -509,7 +509,7 @@
<entry morerows="3">
<para>3</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Display controller.</para>
</entry>
</row>
@ -541,7 +541,7 @@
<entry morerows="3">
<para>4</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Multimedia device</para>
</entry>
</row>
@ -573,7 +573,7 @@
<entry morerows="3">
<para>5</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Memory controller.</para>
</entry>
</row>
@ -605,7 +605,7 @@
<entry morerows="9">
<para>6</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Bridge IOAs.</para>
</entry>
</row>
@ -685,7 +685,7 @@
<entry morerows="3">
<para>7</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Simple communication controllers.</para>
</entry>
</row>
@ -717,7 +717,7 @@
<entry morerows="5">
<para>8</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Generic system peripherals</para>
</entry>
</row>
@ -765,7 +765,7 @@
<entry morerows="4">
<para>9</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Input devices</para>
</entry>
</row>
@ -805,7 +805,7 @@
<entry morerows="2">
<para>A</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Docking stations</para>
</entry>
</row>
@ -829,7 +829,7 @@
<entry morerows="2">
<para>B</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Processors</para>
</entry>
</row>
@ -853,7 +853,7 @@
<entry morerows="2">
<para>C</para>
</entry>
<entry nameend="c3" namest="c2" align="center">
<entry nameend="c3" namest="c2">
<para>Serial bus controllers</para>
</entry>
</row>
@ -883,8 +883,8 @@
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
@ -898,14 +898,14 @@
<emphasis role="bold">Sub-ClassS3-S4</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="13">
<para>0</para>
@ -1274,7 +1274,7 @@
</tbody>
</tgroup>
</table>

</section>

</section>
</chapter>

19
LoPAR/ch_notifications.xml → Error Handling/ch_notifications.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,19 +13,18 @@
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"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
xml:id="dbdoclet.50569337_37595">

<title>Error and Event Notification</title>
<?dbhtml stop-chunking?>

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

153
LoPAR/sec_rtas_error_classes.xml → Error Handling/ch_rtas_error_classes.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,45 +13,45 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<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"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
xml:id="dbdoclet.50569337_29979">

<title>RTAS Error and Event Classes</title>

<para>
<xref linkend="dbdoclet.50569337_82470"/> describes the predefined classes of
error and event notifications that can be presented through the
<emphasis>check-exception</emphasis> and
error and event notifications that can be presented through the
<emphasis>check-exception</emphasis> and
<emphasis>event-scan</emphasis> RTAS functions. More detailed descriptions
of these classes are given later in this chapter.
of these classes are given later in this chapter.
<xref linkend="dbdoclet.50569337_82470"/> defines nodes in the OF device
tree which, through an
tree which, through an
<literal>&#8220;interrupts&#8221;</literal> property, may list the
platform-dependent interrupts related to each class. From this information,
OSs know which interrupts may be handled by calling
OSs know which interrupts may be handled by calling
<emphasis>check-exception</emphasis>. The OF structure for describing these
interrupts is defined in
<xref linkend="dbdoclet.50569368_91814"/>.
<xref linkend="dbdoclet.50569337_82470"/> also defines the mask parameter for the

<emphasis>check-exception</emphasis> and
interrupts is defined in
<xref linkend="LoPAR.DeviceTree"/>.
This document also defines the mask parameter for the
<emphasis>check-exception</emphasis> and
<emphasis>event-scan</emphasis> RTAS functions which limits the search for
errors and events to the classes specified.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_82470">
<title>Error and Event Classes with RTAS Function Call
Mask</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="40*" align="center" />
<colspec colname="c2" colwidth="40*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c1" colwidth="40*" />
<colspec colname="c2" colwidth="40*" />
<colspec colname="c3" colwidth="20*" />
<thead>
<row>
<entry>
@ -61,7 +61,7 @@
</entry>
<entry>
<para>
<emphasis role="bold">OF Node Name(where the
<emphasis role="bold">OF Node Name(where the
<literal>&#8220;interrupts&#8221;</literal> property lists the
interrupts)</emphasis>
</para>
@ -74,7 +74,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Internal Errors</para>
@ -135,84 +135,84 @@
</table>

<variablelist>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Platform Interrupt Event option:</emphasis> The platform
must implement the I/O Events and Errors class type along with the
appropriate
appropriate
<emphasis role="bold"><literal>ibm,io-events</literal></emphasis> node property to specify the
interrupts.</para>
interrupts.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Platform-specific error and event interrupts
that a platform provider wants the OS to enable must be listed in the
that a platform provider wants the OS to enable must be listed in the
<literal>&#8220;interrupts&#8221;</literal> property of the appropriate OF
event class node, as described in
<xref linkend="dbdoclet.50569337_82470"/>.</para>
event class node, as described in
<xref linkend="dbdoclet.50569337_82470"/>.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_80415">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>To enable
platform-specific error and event interrupt notification, OSs must find the
list of interrupts (described in
list of interrupts (described in
<xref linkend="dbdoclet.50569337_82470"/>) for each error and event class in the
OF device tree, and enable them.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>OSs must have interrupt handlers for the
enabled interrupts described in Requirement
<xref linkend="dbdoclet.50569337_80415"/>, which call the RTAS
enabled interrupts described in Requirement
<xref linkend="dbdoclet.50569337_80415"/>, which call the RTAS
<emphasis>check-exception</emphasis> function to determine the cause of the
interrupt.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_31164">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Platforms which
support error and event reporting must provide information to the OS via
the RTAS
<emphasis>event-scan</emphasis> and
the RTAS
<emphasis>event-scan</emphasis> and
<emphasis>check-exception</emphasis> functions, using the reporting format
described in
described in
<xref linkend="dbdoclet.50569337_21249"/>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Optional Extended Error Log information, if
returned by the
<emphasis>event-scan</emphasis> or
returned by the
<emphasis>event-scan</emphasis> or
<emphasis>check-exception</emphasis> functions, must be in the reporting
format described in
format described in
<xref linkend="dbdoclet.50569337_85491"/>.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_36036">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>To provide control
@ -223,9 +223,9 @@
extended error log.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>To prevent the loss of any event
@ -234,9 +234,9 @@
of events other than the one being processed.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>Any interrupts or interrupt controls used for
@ -246,48 +246,48 @@
of interrupt by the processing of another.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_29979"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>If a platform chooses to report multiple
event or error sources through a single interrupt, it must ensure that the
interrupt remains asserted or is re-asserted until
interrupt remains asserted or is re-asserted until
<emphasis>check-exception</emphasis> has been used to process all
outstanding errors or events for that interrupt.</para>
</listitem>
</varlistentry>

</variablelist>

<para>
<emphasis role="bold">Platform Implementation Note:</emphasis> In Requirement
<emphasis role="bold">Platform Implementation Note:</emphasis> In Requirement
<xref linkend="dbdoclet.50569337_31164"/>, although the fixed-part return format
for
<emphasis>check-exception</emphasis> and
for
<emphasis>check-exception</emphasis> and
<emphasis>event-scan</emphasis> is the same, there are some expectations
about what types of error response may be returned from these functions, as
follows:</para>

<itemizedlist>
<listitem>

<para>The
<listitem>
<para>The
<emphasis>event-scan</emphasis> function is mainly intended to report only
errors that have been recovered or are non-critical to the OS, since it is
only called on a periodic basis. As such, it should never be used to report
a Severity greater than &#8220;WARNING&#8221;. More critical errors should
be signaled by an interrupt. Typically, the expected response of an OS to
an
an
<emphasis>event-scan</emphasis> error report is simply to log the error. The
<emphasis>check-exception</emphasis> function may report error information
of any severity.</para>

</listitem>
<listitem>

<para>If
<para>If
<emphasis>event-scan</emphasis> is reporting a critical error (for example,
a checkstop) that occurred before the current boot session, it should not
report it with a &#8220;FATAL&#8221; Severity, even though the condition
@ -297,11 +297,11 @@
RTAS Disposition field for such an error should be
&#8220;FULLY_RECOVERED&#8221;. There is a bit in the extended error log to
indicate these &#8220;residual&#8221; errors.</para>

</listitem>
<listitem>

<para>Although
<para>Although
<emphasis>check-exception</emphasis> can potentially clean up an error and
return a &#8220;FULLY_RECOVERED&#8221; disposition, recovery still may not
occur if the MSR
@ -309,12 +309,13 @@
the RI bit, to determine whether processor state is preserved so that a
return from the machine check interrupt handler can be safely
attempted.</para>

</listitem>
</itemizedlist>

<xi:include href="sec_rtas_error_indications.xml"/>
<xi:include href="sec_rtas_env_epow.xml"/>
<xi:include href="sec_rtas_hot_plug.xml"/>
</chapter>

</section>

18
LoPAR/sec_rtas_error_reporting.xml → Error Handling/ch_rtas_error_reporting.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,16 +13,16 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
xml:id="dbdoclet.50569337_42315">

<title>RTAS Error and Event Information Reporting</title>

<para><emphasis role="bold">Architecture Note:</emphasis> All data formats listed in this section are either
referenced as byte fields (and therefore are independent of Endian
orientation), or an indicator in the data structure describes their Endian
@ -32,5 +32,5 @@
<xi:include href="sec_rtas_error_reporting_introduction.xml"/>
<xi:include href="sec_rtas_error_reporting_return_format.xml"/>
<xi:include href="sec_rtas_error_reporting_location_codes.xml"/>

</section>
</chapter>

0
LoPAR/figures/PAPR-34.gif → Error Handling/figures/PAPR-34.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 50 KiB

0
LoPAR/figures/PAPR-36.gif → Error Handling/figures/PAPR-36.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

0
LoPAR/figures/PAPR-37.gif → Error Handling/figures/PAPR-37.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

0
LoPAR/figures/PAPR-38.gif → Error Handling/figures/PAPR-38.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

0
LoPAR/figures/PAPR-39.gif → Error Handling/figures/PAPR-39.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1012 B

After

Width:  |  Height:  |  Size: 1012 B

0
LoPAR/figures/PAPR-40.gif → Error Handling/figures/PAPR-40.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

0
LoPAR/figures/PAPR-41.gif → Error Handling/figures/PAPR-41.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

0
LoPAR/figures/PAPR-42.gif → Error Handling/figures/PAPR-42.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
LoPAR/figures/PAPR-43.gif → Error Handling/figures/PAPR-43.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

0
LoPAR/figures/PAPR-44.gif → Error Handling/figures/PAPR-44.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

0
LoPAR/figures/PAPR-45.gif → Error Handling/figures/PAPR-45.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
LoPAR/figures/PAPR-46.gif → Error Handling/figures/PAPR-46.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

0
LoPAR/figures/PAPR-47.gif → Error Handling/figures/PAPR-47.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

0
LoPAR/figures/PAPR-48.gif → Error Handling/figures/PAPR-48.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 55 KiB

0
LoPAR/figures/PAPR-49.gif → Error Handling/figures/PAPR-49.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
LoPAR/figures/PAPR-50.gif → Error Handling/figures/PAPR-50.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

0
LoPAR/figures/PAPR-51.gif → Error Handling/figures/PAPR-51.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.8 KiB

After

Width:  |  Height:  |  Size: 9.8 KiB

0
LoPAR/figures/PAPR-52.gif → Error Handling/figures/PAPR-52.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
LoPAR/figures/PAPR-53.gif → Error Handling/figures/PAPR-53.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
LoPAR/figures/PAPR-54.gif → Error Handling/figures/PAPR-54.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

0
LoPAR/figures/PAPR-73.gif → Error Handling/figures/PAPR-73.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 35 KiB

148
Error Handling/pom.xml
Unescape Escape View File

@ -0,0 +1,148 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>

<groupId>org.openpowerfoundation.docs</groupId>
<artifactId>workgroup-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>

<!-- TODO: Rename the artifactID field to some appropriate for your new document -->
<artifactId>LoPAR-Error</artifactId>

<packaging>jar</packaging>
<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>LoPAR-Error</name>

<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name></release.path.name>
<comments.enabled>0</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>

<groupId>org.openpowerfoundation.docs</groupId>

<artifactId>openpowerdocs-maven-plugin</artifactId>
<!-- version set in ../pom.xml -->
<executions>
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>${comments.enabled}</enableDisqus>
<disqusShortname>LoPAR-Error</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
book/appendix nop
book/chapter nop
chapter toc,title
chapter/section nop
section toc
part toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>1</sectionAutolabel>
<tocSectionDepth>3</tocSectionDepth>
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>

<!-- TODO: Rename the webhelpDirname field to the new directory for new document -->
<webhelpDirname>LoPAR_Error_Handling</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>LoPAR_Error_Handling</pdfFilenameBase>

<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
Consult with the Work Group Chair or a Technical Steering Committee member if you have
questions about which value to select.
If no value is provided below, the document will default to "Work Group Notes".-->
<workProduct>workgroupNotes</workProduct>
<!-- workProduct>workgroupSpecification</workProduct -->
<!-- workProduct>candidateStandard</workProduct -->
<!-- workProduct>openpowerStandard</workProduct -->

<!-- TODO: Set the appropriate security policy for the document. For documents
which are not "public" this will affect the document title page and
create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

public = this document may be shared outside the
foundation and thus this setting must be
used only when completely sure it allowed
foundationConfidential = this document may be shared freely with
OpenPOWER Foundation members but may not be
shared publicly
workgroupConfidential = this document may only be shared within the
work group and should not be shared with
other Foundation members or the public

The appropriate starting security for a new document is "workgroupConfidential". -->
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->

<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

published = this document has completed all reviews and has
been published
draft = this document is actively being updated and has
not yet been reviewed
review = this document is presently being reviewed

The appropriate starting security for a new document is "draft". -->
<!-- documentStatus>draft</documentStatus -->
<documentStatus>review</documentStatus>
<!-- documentStatus>publish</documentStatus -->

</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
<!-- TODO: If you desire, you may change the following filename to something more appropriate for the new document -->
bk_main.xml
</includes>

<!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
<!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
<includeCoverLogo>1</includeCoverLogo>
<coverUrl>www.openpowerfoundation.org</coverUrl>
</configuration>
</plugin>
</plugins>
</build>
</project>

42
LoPAR/sec_error_introduction.xml → Error Handling/sec_error_introduction.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,16 +13,16 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

<title>Introduction</title>

<para>RTAS provides a mechanism which helps OSs avoid the need for
platform-dependent code that checks for, or recovers from, errors or
exceptional conditions. The mechanism is used to return information about
@ -31,28 +31,28 @@
voltage out-of-bounds) which may need OS attention. This permits RTAS to
pass hardware event information to the OS in a way which is abstracted from
the platform hardware. This mechanism primarily presents itself to the OS
via two RTAS functions,
<emphasis>event-scan</emphasis> and
<emphasis>check-exception</emphasis>, which are described further in
<xref linkend="dbdoclet.50569332_16852"/>. A further RTAS function,
via two RTAS functions,
<emphasis>event-scan</emphasis> and
<emphasis>check-exception</emphasis>, which are described further in
<xref linkend="dbdoclet.50569332_16852"/>. A further RTAS function,
<emphasis>rtas-last-error</emphasis>, is also provided to return
information about hardware failures detected specifically within an RTAS
call.</para>

<para>The
<para>The
<emphasis>event-scan</emphasis> function is called periodically to check for
the presence or past occurrence of a hardware event, such as a soft failure
or voltage condition, which did not cause a program exception or interrupt
(for example, an ECC error detected and corrected by background scrubbing
activity). The
activity). The
<emphasis>check-exception</emphasis> function is called to provide further
detail on what platform event has occurred when certain exceptions or
interrupts are signaled. The events reported by these two functions are
mutually exclusive on any given platform; that is, a platform may choose to
notify the OS of a particular event type either through
<emphasis>event-scan</emphasis> or through an interrupt and
notify the OS of a particular event type either through
<emphasis>event-scan</emphasis> or through an interrupt and
<emphasis>check-exception</emphasis>, but not both.</para>

<para>Since firmware is platform-specific, it can examine hardware
registers, can often diagnose many kinds of hardware errors down to a root
cause, and may even perform some very limited kinds of error recovery on
@ -63,13 +63,13 @@
involvement. Firmware may not, in many cases, be able to determine all the
details of an error, so there are also returned values which indicate this
fact. Firmware may optionally provide extended error diagnostic
information, as described in
information, as described in
<xref linkend="dbdoclet.50569337_79682"/>.</para>

<para>The abstractions provided by this architecture enable the handling of
most platform errors and events without integrating platform-specific code
into each supported OS.</para>

<para><emphasis role="bold">Architecture Note:</emphasis> It is not a goal of the firmware to diagnose all
hardware failures. Most I/O device failures, for example, will be detected
and recovered by an associated device driver. Firmware attempts to
@ -81,5 +81,5 @@
contain specific hardware knowledge, or could use firmware to collect a
minimum set of error information which could then be used by diagnostics to
further analyze the cause of the error.</para>

</section>

87
Error Handling/sec_error_reporting.xml
Unescape Escape View File

@ -0,0 +1,87 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dbdoclet.50569332_16852">
<title>Error and Event Reporting</title>
<para>The error and event reporting RTAS calls are designed to provide an
abstract interface into hardware registers in the system that may contain
correctable or non-correctable errors and to provide an abstract interface
to certain platform events that may be of interest to the OS. Such errors
and events may be detected either by a periodic scan or by an exception trap.
</para>
<para>These functions are not intended to replace the normal error handling
in the OS. Rather, they enhance the OS&#8217;s abilities by providing an
abstract interface to check for, report, and recover from errors or events
on the platform that are not necessarily known to the OS. </para>
<para>The OS uses the error and event RTAS calls in two distinct ways:</para>
<orderedlist>
<listitem>
<para>Periodically, the OS calls <emphasis> event-scan</emphasis>
<anchor xml:id="dbdoclet.50569332_marker-7330" xreflabel="event-scan"/> to have
the system firmware check for any errors or events that have occurred. </para>

</listitem>
<listitem>
<para>Whenever the OS receives an interrupt or exception that it cannot
fully process, it calls <emphasis> check-exception.</emphasis></para>
</listitem>
</orderedlist>
<para>The first case covers all errors and events that do not signal their
occurrence with an interrupt or exception. The second case covers those
errors and events that do signal with an interrupt or exception. It is
platform dependent whether any specific error or event causes an interrupt
on that platform.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16852"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>RTAS must return the event generated by a
particular interrupt or event source by either
<emphasis> check-exception</emphasis> or <emphasis> event-scan</emphasis>,
but not both.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_16852"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis> check-exception </emphasis>
and <emphasis> event-scan</emphasis> , on a 64-bit capable platform, must
be able to handle platform resources that are accessed using 64-bit
addresses when instantiated in 32-bit mode. </para>
</listitem>
</varlistentry>

</variablelist>
</section>

124
LoPAR/sec_rtas_env_epow.xml → Error Handling/sec_rtas_env_epow.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,16 +13,16 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<section 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"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dbdoclet.50569337_17513">

<title>Environmental and Power Warnings</title>

<para>Environmental and Power Warnings (EPOW) is an option that provides
a means for the platform to inform the OS of these types of events. The
intent is to enable the OS to provide basic information to the user about
@ -32,86 +32,86 @@
the loss of power. Even on platforms that provide hardware protection of
data during environmental events, EPOW notification allows discrimination
between I/O errors caused by hardware failures versus EPOW events.</para>

<para>These warnings include action codes that the platform can use to
influence the OS behavior when various hardware components fail. For
example, a fan failure where the system can continue to operate in the
safe cooling range may just generate an action code of WARN_COOLING, but
a fan failure where the system cannot operate in the safe cooling range
may generate an action code of SYSTEM_HALT.</para>

<para><emphasis role="bold">Implementation Note:</emphasis> Hardware cannot assume that the OS will
process or take action on these warnings. These warnings are only
provided to the OS in order to allow the OS a chance to cleanly abort
operations in progress at the time of the warning. Hardware still assumes
responsibility for preventing hardware damage due to environmental or
power problems.</para>

<para>An OS that wants to be EPOW-aware will look for the
<para>An OS that wants to be EPOW-aware will look for the
<emphasis>epow-events</emphasis> node in the OF device tree, enable the
interrupts listed in its
interrupts listed in its
<literal>&#8220;interrupts&#8221;</literal> property, and provide an
interrupt handler to call
interrupt handler to call
<emphasis>check-exception</emphasis> when one of those interrupts are
received.</para>

<para>When an EPOW event occurs, whether reported by
<emphasis>check-exception</emphasis> or
<para>When an EPOW event occurs, whether reported by
<emphasis>check-exception</emphasis> or
<emphasis>event-scan</emphasis>, RTAS will directly pass back the EPOW
sensor value as part of the Extended Error Log format as described in
sensor value as part of the Extended Error Log format as described in
<xref linkend="dbdoclet.50569337_39498"/>, assuming the extended log is
requested. Doing so avoids the need for the OS to make an extra RTAS call
to obtain the sensor value. For critical power problems, the
to obtain the sensor value. For critical power problems, the
<emphasis>check-exception</emphasis> function is used to immediately
report changes of state to the OS, while the
report changes of state to the OS, while the
<emphasis>get-sensor-state</emphasis> function allows the OS to monitor
the condition (for example, loss of AC power) to see if the problem
corrects itself.</para>

<variablelist>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para> If the platform supports Environmental and
Power Warnings by including a EPOW device tree entry, then the platform
must support the EPOW sensor for the
must support the EPOW sensor for the
<emphasis>get-sensor-state</emphasis> RTAS function.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para> The EPOW sensor, if provided, must contain
the EPOW action code (defined in
the EPOW action code (defined in
<xref linkend="dbdoclet.50569337_45557"/>) in the least significant 4
bits. In cases where multiple EPOW actions are required, the action code
with the highest numerical value (where 0 is lowest and 7 is highest)
must be presented to the OS. The platform may implement any subset of
these action codes, but must operate as described in
these action codes, but must operate as described in
<xref linkend="dbdoclet.50569337_45557"/> for those it does implement.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>To ensure adequate response time,
platforms which implement the EPOW_MAIN_ENCLOSURE or EPOW_POWER_OFF
action codes must do so via interrupt and
<emphasis>check-exception</emphasis> notification, rather than by
<emphasis>event-scan</emphasis> notification.
<emphasis>(Except as modified by Requirement
action codes must do so via interrupt and
<emphasis>check-exception</emphasis> notification, rather than by
<emphasis>event-scan</emphasis> notification.
<emphasis>(Except as modified by Requirement
<xref linkend="dbdoclet.50569337_83439"/>)</emphasis></para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_83439">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>If the platform
@ -120,54 +120,54 @@
to the EPOW event.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>For interrupt-driven EPOW events, the
platform must ensure that an EPOW interrupt is not lost in the case where
a numerically higher-priority EPOW event occurs between the time when
a numerically higher-priority EPOW event occurs between the time when
<emphasis>check-exception</emphasis> gathers the sensor value and when it
resets the interrupt.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569337_17513"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>For SYSTEM_SHUTDOWN EPOW class 3, after a
SYSTEM_SHUTDOWN EPOW commences and when the delay interval timer expires,
if an
if an
<emphasis role="bold"><literal>&#8220;ibm,recoverable-epow3&#8221;</literal></emphasis>
encode-null
property in the
property in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node is present, then the OS code that manages
preserving storage must check the EPOW sensor state and the
preserving storage must check the EPOW sensor state and the
<emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis>
property if present. A normal boot must only occur when the EPOW sensor state
indicates that the EPOW condition requiring a shutdown no longer exists
(EPOW 0) and the
<emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis>
(EPOW 0) and the
<emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis>
is not present. Otherwise, the code that manages preserving storage must take
the action as identified by the property.</para>
</listitem>
</varlistentry>

</variablelist>

<para><emphasis role="bold">Implementation Note:</emphasis> One way for hardware to prevent the loss of an
EPOW interrupt is by deferring the generation of a new EPOW interrupt
until the existing EPOW interrupt is reset by a call to the RTAS
until the existing EPOW interrupt is reset by a call to the RTAS
<emphasis>check-exception</emphasis> function. Another way is to ignore
resets to the interrupt until all EPOW events have been reported.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_45557">
<title>EPOW Action Codes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="30*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
@ -181,14 +181,14 @@
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>EPOW_RESET/MESSAGE</para>
@ -289,32 +289,32 @@
</tbody>
</tgroup>
</table>

<para><emphasis role="bold">Software Implementation Note:</emphasis> A recommended OS processing method
for an EPOW_MAIN_ENCLOSURE event is as follows:</para>

<itemizedlist>
<listitem>

<para>Prepare for shutdown, mask the EPOW interrupt, and wait for 50
milliseconds. Then call get-sensor-state to read the EPOW sensor.</para>

</listitem>
<listitem>

<para>If the EPOW action code is unchanged, wait an additional 50
milliseconds.</para>

</listitem>
<listitem>

<para>If the action code is EPOW_POWER_OFF, attempt to power off.
Otherwise, the power condition may have stabilized, so interrupts may be
enabled and normal operation resumed.</para>

</listitem>
</itemizedlist>

<para>
<emphasis role="bold">Implementation Note:</emphasis> EPOW_RESET (EPOW action code 0)
may be used to indicate that a previously reported EPOW condition is no
@ -324,7 +324,7 @@
error log that specified the type of WARN_POWER EPOW generated would be
set in the EPOW_RESET error log to indicate the specific EPOW event that
was reset.</para>

<para>Systems that do not support an EPOW interrupt would generally be
unable to support the EPOW action codes 5 and 7. In those cases, there
could not be an EPOW event to indicate a loss of power. However, after
@ -332,5 +332,5 @@
the system had lost power previously and the power had been restored. The
EPOW_RESET should only be used in this way if the system is unable to
generate an EPOW class 5 or class 7.</para>

</section>

112
LoPAR/sec_rtas_error_indications.xml → Error Handling/sec_rtas_error_indications.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,21 +13,21 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<section 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"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="Internal_Error_Indications">

<title>Internal Error Indications</title>

<para>Hardware may detect a variety of problems during operation, ranging
from soft errors which have already been corrected by the time they are
reported, to hard errors of such severity that the OS (and perhaps the
hardware) cannot meaningfully continue operation. The mechanisms
described in
described in
<xref linkend="dbdoclet.50569337_66258"/> are used to report such errors to the
OS. This section describes the architectural sources of errors, and
describes a method that platforms can use to report the error. All OSs
@ -36,7 +36,7 @@
may be introduced via RTAS, and the OS may not have to handle the error
directly. More robust error detection, reporting, and correcting are at
the option of the hardware vendor.</para>

<para>
<anchor xml:id="dbdoclet.50569337_marker-13885" xreflabel="" />
<anchor xml:id="dbdoclet.50569337_marker-13886" xreflabel="" />The
@ -51,12 +51,12 @@
handle such cases, a special hardware mechanism may be provided to gather
and store residual error data, to be analyzed when the system goes
through a subsequent successful reboot.</para>

<para>Less critical internal errors may also be signaled to the OS
through a platform-specific interrupt in the &#8220;Internal
Errors&#8221; class, or by periodic polling with the
Errors&#8221; class, or by periodic polling with the
<emphasis>event-scan</emphasis> RTAS function.</para>

<para><emphasis role="bold">Architecture Note:</emphasis> The machine check interrupt will not be listed
in the OF node for the &#8220;Internal Errors&#8221; class, since it is a
standard architectural mechanism. The machine check interrupt mechanism
@ -69,55 +69,55 @@
connection to the processor machine check interrupt pin, or via a system
bus error indicator (for example, Transfer Error Acknowledge -
TEA).</para>

<variablelist>

<varlistentry xml:id="dbdoclet.50569337_38528">
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>OSs must set
MSRME=1 prior to the occurrence of a machine check interrupt in order to
enable machine check processing via the
<emphasis>check-exception</emphasis> RTAS function.</para>

<para>
<emphasis role="bold">Architecture Note:</emphasis> Requirement
<emphasis role="bold">Architecture Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569337_38528"/> is not applicable when the FWNMI
option is used.</para>

</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_36603">
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>For
hardware-detected errors, platforms must generate error indications as
described in
described in
<xref linkend="dbdoclet.50569337_30773"/>, unless the error can be handled
through a less severe platform-specific interrupt, or the nature of the
error forces a checkstop condition.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Platforms which detect and report the
errors described in
errors described in
<xref linkend="dbdoclet.50569337_30773"/> must provide information to the OS
via the RTAS
via the RTAS
<emphasis>check-exception</emphasis> function, using the reporting format
described in
described in
<xref linkend="dbdoclet.50569337_21249"/>.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569337_16228">
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
<term><emphasis role="bold">R1-<xref linkend="Internal_Error_Indications"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>To prevent error
@ -126,7 +126,7 @@
interrupt signaled via the external machine check interrupt pin.</para>
</listitem>
</varlistentry>

</variablelist>

<para>
@ -135,8 +135,8 @@

<orderedlist>
<listitem>

<para>The intent of Requirement
<para>The intent of Requirement
<xref linkend="dbdoclet.50569337_36603"/> is to define standard error
notification mechanisms for different hardware error types. For most
hardware errors, the signaling mechanism is the machine check interrupt,
@ -156,15 +156,15 @@
summarize, platforms should not use platform-specific interrupts to
signal hardware errors unless there is a complete hardware/RTAS platform
solution for handling such errors.</para>

</listitem>
<listitem>

<para>The intent of Requirement
<para>The intent of Requirement
<xref linkend="dbdoclet.50569337_16228"/> is that most hardware errors would be
signaled simultaneously to all processors, so that processors could
synchronize the error handling process; that is, one processor would be
chosen to do the call to
chosen to do the call to
<emphasis>check-exception</emphasis>, while the other processors remained
idle so that they would not interfere with RTAS while it gathered machine
check error data. While this is a straightforward wiring solution for
@ -178,13 +178,13 @@
such propagation should be avoided, and such errors should be signaled
through the machine check interrupt pin to ensure proper error
handling.</para>

</listitem>
</orderedlist>

<section xml:id="dbdoclet.50569337_52952">
<title>Error Indication Mechanisms</title>

<para>
<xref linkend="dbdoclet.50569337_30773"/> describes the mechanisms by
which software will be notified of the occurrence of operational failures
@ -198,12 +198,12 @@
<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_30773">
<title>Error Indications for System Operations</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" align="center" />
<colspec colname="c6" colwidth="20*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<colspec colname="c6" colwidth="20*" />
<thead>
<row>
<entry>
@ -238,7 +238,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Processor</para>
@ -451,7 +451,7 @@
</entry>
<entry>
<para>Firmware receives a machine check, OS receives
all=1&#8217;s data along with a
all=1&#8217;s data along with a
<emphasis>Status</emphasis> of -1 from the RTAS call</para>
</entry>
<entry>
@ -466,7 +466,7 @@
</entry>
<entry>
<para>All-1&#8217;s data returned, along with a
&#8220;Success&#8221;
&#8220;Success&#8221;
<emphasis>Status</emphasis> from the RTAS call</para>
</entry>
<entry>
@ -482,7 +482,7 @@
<para>Various, except no response from IOA</para>
</entry>
<entry>
<para>Firmware receives a machine check, OS receives a
<para>Firmware receives a machine check, OS receives a
<emphasis>Status</emphasis> of -1 from the RTAS call</para>
</entry>
<entry>
@ -496,7 +496,7 @@
<para>No response from an IOA</para>
</entry>
<entry>
<para>Operation ignored, OS receives a &#8220;Success&#8221;
<para>Operation ignored, OS receives a &#8220;Success&#8221;
<emphasis>Status</emphasis> from the RTAS call</para>
</entry>
<entry>
@ -603,21 +603,21 @@
</entry>
<entry>
<para>Various, including but not limited to:</para>

<itemizedlist>
<itemizedlist>
<listitem>
<para>Invalid addr accepted by a bridge</para>
</listitem>

<listitem>
<para>TCE extent</para>
</listitem>

<listitem>
<para>TCE Page Mapping and Control mis-match or invalid
TCE</para>
</listitem>
</itemizedlist>
</itemizedlist>

</entry>
<entry>
@ -696,7 +696,7 @@
</tbody>
</tgroup>
</table>

<para><emphasis role="bold">Implementation Note:</emphasis> IOAs should, whenever possible, detect the
occurrence of PCI errors on DMA and report them via an external interrupt
(for possible device driver recovery) or retry the operation. Since
@ -705,7 +705,7 @@
cause a catastrophic error. Systems which wish to recover from these
types of errors should choose devices and device drivers which are
designed to handle them correctly.</para>

</section>

</section>

16
LoPAR/sec_rtas_error_reporting_introduction.xml → Error Handling/sec_rtas_error_reporting_introduction.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,16 +13,16 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

<title>Introduction</title>

<para>This section describes the data formats used to report events and
errors from RTAS to the OS. A common format is used for errors and events
to simplify software both in RTAS and in the OS. Both errors and events
@ -36,5 +36,5 @@
mapping exists, and platform features may not be fully supported by the
OS. In such cases, error reports may also be non-specific, leaving
platform-specific details to platform-aware software.</para>

</section>
</section>

22
LoPAR/sec_rtas_error_reporting_location_codes.xml → Error Handling/sec_rtas_error_reporting_location_codes.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,25 +13,25 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

<title>Location Codes</title>

<para>This document defines an architecture extension for physical
location codes. One use of location codes is to append failing location
information to error logs returned by the
<emphasis>event-scan</emphasis> and
<emphasis>check-exception</emphasis> RTAS services. Refer to
<xref linkend="dbdoclet.50569341_35066"/> for more information on the
information to error logs returned by the
<emphasis>event-scan</emphasis> and
<emphasis>check-exception</emphasis> RTAS services. Refer to
<xref linkend="LoPAR.RTAS"/> for more information on the
format and use of location codes. For event logs with Version 6 or later,
the location code of FRU call out is contained in the Primary SRC
section, FRU call out sub-section of the Platform Event Log
format.</para>

</section>

153
LoPAR/sec_rtas_error_reporting_return_format.xml → Error Handling/sec_rtas_error_reporting_return_format.xml
Unescape Escape View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
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.
@ -311,9 +311,10 @@
indicated in decimal unless noted otherwise.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_21249">
<title>RTAS Event Return Format (Fixed Part)</title>
<title>RTAS Event Return Format (Fixed Part)
<emphasis>(Continued)</emphasis></title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c1" colwidth="30*" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
@ -323,7 +324,7 @@
number(s))</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description, Values (Described in
<xref linkend="dbdoclet.50569337_75663"/>)</emphasis>
@ -331,7 +332,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Version (0:7)</para>
@ -663,8 +664,8 @@
<table frame="all" pgwide="1" xml:id="dbdoclet.50569337_85491">
<title>RTAS General Extended Event Log Format, Version 6</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -674,12 +675,12 @@
<entry>
<para><emphasis role="bold">Bit</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry morerows="7">
<para>0</para>
@ -860,8 +861,8 @@
<title>Overview of Platform Event Log Format, Version
6</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -871,12 +872,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>12-15</para>
@ -1075,8 +1076,8 @@
<title>Platform Event Log Format, Version 6, Main-A
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -1086,12 +1087,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -1287,8 +1288,8 @@
<title>Platform Event Log Format, Version 6, Main-B
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -1298,12 +1299,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -1896,8 +1897,8 @@
<title>Platform Event Log Format, Version 6, Logical
Resource Identification Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -1907,12 +1908,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -2051,8 +2052,8 @@
<title>Platform Event Log Format, Version 6, Primary SRC
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -2062,12 +2063,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -2356,8 +2357,8 @@
<title>Platform Event Log Format, Version 6, FRU Call-out
Structure</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -2367,12 +2368,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -2746,8 +2747,8 @@
<title>Platform Event Log Format, Version 6, Dump Locator
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -2757,12 +2758,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -2927,8 +2928,8 @@
<title>Platform Event Log Format, Version 6, EPOW
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -2938,12 +2939,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -3088,8 +3089,8 @@
<title>Platform Event Log Format, Version 6, IO Events
Section</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3099,12 +3100,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -3286,8 +3287,8 @@
<title>Platform Event Log Format, Version 6, Failing
Enclosure MTMS</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3297,12 +3298,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -3431,12 +3432,12 @@
<title>Platform Event Log Format, Version 6, Impacted
Partitions</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" align="center" />
<colspec colname="c6" colwidth="20*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<colspec colname="c6" colwidth="20*" />
<thead>
<row>
<entry>
@ -3459,7 +3460,7 @@
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0</para>
@ -3583,8 +3584,8 @@
<title>Platform Error Event Log Format, Version 6, Failing
Memory Address</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3594,12 +3595,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -3720,8 +3721,8 @@
<table frame="all" pgwide="1">
<title>UE Error Information</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3731,12 +3732,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x11</para>
@ -3819,8 +3820,8 @@
<table frame="all" pgwide="1">
<title>SLB Error Information</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3830,12 +3831,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x11</para>
@ -3901,8 +3902,8 @@
<table frame="all" pgwide="1">
<title>ERAT Error Information</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3912,12 +3913,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x11</para>
@ -3983,8 +3984,8 @@
<table frame="all" pgwide="1">
<title>TLB Error Information</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c1" colwidth="10*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="80*" />
<thead>
<row>
@ -3994,12 +3995,12 @@
<entry>
<para><emphasis role="bold">Length in Bytes</emphasis></para>
</entry>
<entry align="center">
<entry>
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x11</para>

42
LoPAR/sec_rtas_hot_plug.xml → Error Handling/sec_rtas_hot_plug.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,34 +13,34 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
<section 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"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="Hot_Plug_Events">

<title>Hot Plug Events</title>

<para>Hot Plug Events, when implemented, are reported through
<para>Hot Plug Events, when implemented, are reported through
either the event-scan RTAS call or a hotplug interrupt.</para>

<para>An OS that wants to be notified of hotplug events will need to
set the appropriate arch-vector bit. Look for the hot-plug-events
node in the /event-sources node of the OF device tree (see
<xref linkend="sec_papr_bindings_hot_plug_events" />), enable the interrupts listed
in its “interrupts” property and provide an interrupt handler to call
<para>An OS that wants to be notified of hotplug events will need to
set the appropriate arch-vector bit. Look for the hot-plug-events
node in the /event-sources node of the OF device tree (see
<xref linkend="LoPAR.DeviceTree" />), enable the interrupts listed
in its “interrupts” property and provide an interrupt handler to call
check-exception when one of those interrupts are received.</para>

<para>When a hotplug event occurs, whether reported by check-exception
or event-scan, RTAS will directly pass back the Hotplug Event Log as
<para>When a hotplug event occurs, whether reported by check-exception
or event-scan, RTAS will directly pass back the Hotplug Event Log as
described in <xref linkend="table.error.hotplug" />.</para>

<variablelist>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="Hot_Plug_Events"
<term><emphasis role="bold">R1-<xref linkend="Hot_Plug_Events"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>If FRUs can be hot plugged in the system
@ -48,7 +48,7 @@
signaling the OS about the event.</para>
</listitem>
</varlistentry>

</variablelist>

</section>

29
LoPAR/ch_rtas.xml
Unescape Escape View File

@ -1,29 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

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

</chapter>

174
LoPAR/sec_pa_processor_binding_terms.xml
Unescape Escape View File

@ -1,174 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

<title>Terms</title>

<para>This standard uses technical terms as they are defined in the
IEEE Std 1275-1994 Standard and other
documents cited in &#8220;References&#8221;, plus the following
terms:</para>

<variablelist>

<varlistentry>
<term><emphasis role="bold">core, core specification, core document</emphasis></term>
<listitem>
<para>Refers to IEEE Std 1275-1994 Standard for Boot (Initialization,
Configuration) Firmware, Core Practices and Requirements</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">core errata</emphasis></term>
<listitem>
<para>Refers to Core Errata, IEEE P1275.7</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">effective address</emphasis></term>
<listitem>
<para>The 64- or 32-bit address computed by the processor
when executing a Storage Access or Branch instruction, or when fetching the
next sequential instruction. If address translation is disabled, the real
address is the same as the effective address. If address translation is
enabled, the real address is determined by, but not necessarily identical
to, the effective address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">linkage area</emphasis></term>
<listitem>
<para>An area within the stack that is reserved for saving
certain registers across procedure calls in PA run-time models. This area
is reserved by the caller and is allocated above the current stack pointer
(<literal>%r1</literal>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">Open Firmware (OF)</emphasis></term>
<listitem>
<para>The firmware architecture defined by
<xref linkend="dbdoclet.50569387_45524" /> and
<xref linkend="dbdoclet.50569387_14175" />, or, when used as an adjective,
a software component compliant with the core specification and
errata.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">procedure descriptor</emphasis></term>
<listitem>
<para>A data structure used by some PA run-time models
to represent a C &#8220;pointer to procedure&#8221;. The first word of this
structure contains the actual address of the procedure.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">processor bus</emphasis></term>
<listitem>
<para>The bus that connects the CPU chip to the system.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">real address</emphasis></term>
<listitem>
<para>An address that the processor presents on the processor
bus.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">real-mode</emphasis></term>
<listitem>
<para>The mode in which OF and its client are running with
translation disabled; all addresses passed between the client and OF are
real (i.e., hardware) addresses.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">segmented address translation</emphasis></term>
<listitem>
<para>The process whereby an Effective Address (EA) is translated into a
Virtual Address (VA) and the virtual address is translated into a Real
Address (RA). (see
<xref linkend="dbdoclet.50569374_41703" />and Book III of
<xref linkend="dbdoclet.50569387_99718" />for more detail.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">suspend</emphasis></term>
<listitem>
<para>A form of Power Management characterized by a fast recovery
to full operation. Typically, system memory will not be powered off while
in the suspend state.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">Table of Contents (TOC)</emphasis></term>
<listitem>
<para>A data structure used by some PA run-time models that is used for
access to global variables and for inter-module linkage. When a TOC is
used,
<emphasis>%r2</emphasis> contains its base address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">Virtual Address</emphasis></term>
<listitem>
<para>In IEEE 1275 parlance, the address that a program uses to access
a memory location or
memory-mapped device register. Depending on the presence or absence of
memory mapping hardware in the system, and whether or not that mapping
hardware is enabled, a virtual address may or may not be the same as the
physical (real) address that appears on an external bus. The IEEE 1275
definition of &#8220;virtual address&#8221; corresponds to The PA's
definition of &#8220;effective address.&#8221; Except as noted, this
document uses the IEEE 1275 definition of virtual address.</para>

<para>In PA parlance, an internal address within the PA address
translation mechanism, used
as in intermediate term in the translation of an effective address to the
corresponding real address.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">virtual-mode</emphasis></term>
<listitem>
<para>The mode in which OF and its client share a single
virtual address space, and address translation is enabled; all addresses
passed between the client and OF are virtual (translated) addresses.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

620
LoPAR/sec_rtas_configure_kernel_dump.xml
Unescape Escape View File

@ -1,620 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_67111">
<title><emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call</title>

<para>This RTAS call is used to register and unregister with the platform
a data structure describing kernel dump information. This dump
information is preserved as needed by the platform in support of a
platform assisted kernel dump option.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
option:</emphasis> The platform must implement the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call using the
argument call buffer defined by
<xref linkend="dbdoclet.50569332_24141" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24141">
<title><emphasis>ibm,configure-kernel-dump</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<tbody valign="middle" >
<row>
<entry>
<para>Parameter Type</para>
</entry>
<entry>
<para>Name</para>
</entry>
<entry align="center">
<para>Values</para>
</entry>
</row>
<row>
<entry morerows="5" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,configure-kernel-dump</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Command</emphasis>
</para>
</entry>
<entry>
<para>1: Register for future kernel dump</para>
<para>2: Unregister for future kernel dump</para>
<para>3: Complete/Invalidate current kernel dump</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work_buffer_address</emphasis>
</para>
</entry>
<entry>
<para>When command is 1: Register for future kernel dump,
points to a structure as defined in
<xref linkend="dbdoclet.50569332_76933" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work_buffer_length</emphasis>
</para>
</entry>
<entry>
<para>Length of Kernel Dump Memory Structure when defined
above</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>0: Success</para>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error</para>
<para>-9: Dump Already Registered</para>
<para>-10: Dump Active</para>
<para>990x:Extended Delay</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
option:</emphasis> The work-buffer address and work-buffer-length for the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call must point to an
RMR-memory buffer that contains the structures described in
<xref linkend="dbdoclet.50569332_76933" />, whenever the command is 1,
register for future kernel dump; otherwise the call may return -3,
&#8220;Parameter Error.&#8221;</para>
<para>The Dump Memory Structure specified in
<xref linkend="dbdoclet.50569332_76933" /> is passed by the operating
system during a
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call. It is also
reported by the platform using the
<emphasis>ibm,kernel-dump</emphasis> RTAS property after a dump has been
initiated.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76933">
<title>Kernel Assisted Dump Memory Structure</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="1*" align="center" />
<colspec colname="c3" colwidth="1*" align="center" />
<colspec colname="c4" colwidth="2*" />
<colspec colname="c5" colwidth="2*" />
<thead>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Header</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Offset</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Number of Bytes</para>
</entry>
<entry nameend="c5" namest="c4" align="center">
<para>Value</para>
</entry>
</row>
<row>
<entry>
<para>0x0</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Format Version = 0x00000001</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of Kernel Dump Sections</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Status Flags</para>
<para>A bit mask with value</para>
<para>0x8000 = Dump performed (Set to 0 by caller of the
ibm,configure-kernel-dump call)</para>
<para>0x4000 = Dump was triggered by the previous system boot
(set by platform)</para>
<para>0x2000 = Dump error occurred (set by platform)</para>
<para>All other bits reserved</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Offset to first Kernel Dump Section, offset from the
beginning of the Structure</para>
</entry>
</row>
<row>
<entry>
<para>0xc</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of bytes in a block of the dump-disk, if data to
be written to a dump-disk, If not, should be set to 0
(indicating the no disk dump option.)</para>
</entry>
</row>
<row>
<entry>
<para>0x10</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Starting block# offset on dump-disk (set to 0 for the no
disk dump option)</para>
</entry>
</row>
<row>
<entry>
<para>0x18</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Number of blocks on dump-disk usable for dump (set to 0
for the no disk dump option)</para>
</entry>
</row>
<row>
<entry>
<para>0x20</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Offset from start of structure to a Null-terminated
Dump-disk path string (set to 0 for the no disk dump
option)</para>
</entry>
</row>
<row>
<entry>
<para>0x24</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Maximum time allowed (milliseconds) after
Non-Maskable-Interrupt for the OS to call
<emphasis>ibm,configure-kernel-dump</emphasis>
<emphasis>Function</emphasis> 2 (unregister) to prevent an
automatic dump-reboot (set to 0 to disable the automatic
dump-reboot function)</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Dump-disk Path String</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Offset specified above</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Varies</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Null-terminated Dump-disk path string specifying the
dump-disk. If no disk dump option is indicated, this section is
not included.</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>First Kernel Dump Section</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Offset specified above</para>
</entry>
<entry nameend="c3" namest="c2">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Request Flags:</para>
<para>A bit-mask</para>
<para>Bit 0x00000001 When set, firmware to copy source data to
partition memory. This option must be selected if no disk dump
option is indicated.</para>
<para>All other bit values reserved</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+4</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Source Data type, describes section of dump memory being
described</para>
<para>0x0001 = CPU State Data</para>
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
<para>0x0011 = Real Mode Region</para>
<para>0x0012 = Dump OS identified string (identifies that the
dump is for a particular OS type and version)</para>
<para>0x0100 - 0xFFFF OS defined source types</para>
<para>All Other values reserved</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+6</para>
</entry>
<entry nameend="c3" namest="c2">
<para>2</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Dump Error Flags (set by platform)</para>
<para>Bit mask</para>
<para>0x8000 = Invalid section data type</para>
<para>0x4000 = Invalid source address</para>
<para>0x2000 = Requested section length exceeds source</para>
<para>0x1000 = Invalid partition destination address</para>
<para>0x0800 = Partition memory destination too small</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+8</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Source address (logical address if section came from
partition memory, or byte offset if section is platform
memory)</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+16</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Requested data length, represents number of bytes to
dump</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+24</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Actual data length, number of bytes dumped</para>
</entry>
</row>
<row>
<entry>
<para>Section Start+32</para>
</entry>
<entry nameend="c3" namest="c2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Destination address, logical address used for sections
not written to disk by the platform, always required for a Real
mode region section and for all sections when the no disk dump
option is used.</para>
</entry>
</row>
<row>
<entry nameend="c5" namest="c1">
<para>
<emphasis>Subsequent Sections</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Previous Section Start+40</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Start of Next Section</para>
</entry>
<entry nameend="c5" namest="c4">
<para>A total of up to nine additional 40 bytes sections with
values as described in the First Section may be specified so
long as the entire structure does not exceed 512 bytes for
version 1.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis>ibm,os-term</emphasis> RTAS call, or on a system reset without
an
<emphasis>ibm,nmi-interlock</emphasis> RTAS call, if the platform has a
dump structure registered through the
<emphasis>ibm,configure-kernel-dump</emphasis> call, the platform must
process each registered kernel dump section as required and, when
available, present the dump structure information to the operating system
through the
<emphasis role="bold"><literal>&#8220;ibm,kernel-dump&#8221;</literal></emphasis> property, updated with
status for each dump section, until the dump has been invalidated through
the
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
register or unregister for a dump while a dump is currently active, the
platform must return a
<emphasis>Status</emphasis> of -9, &#8220;Dump Active&#8221; indicating
that a dump has been copied by the platform and a call must be made to
complete/invalidate the active dump before another call to register or
unregister a dump can be completed successfully.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
register a dump after a dump has already been registered by a call, the
platform must return a
<emphasis>Status</emphasis> of -8, &#8220;Dump Already Registered&#8221;
unless an intervening call was made to invalidate the previously
registered dump.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> Partition memory not specifically mentioned in the call
structure must be preserved by the platform at the same location as
existed prior to the os termination or platform reboot.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> The platform must present the RTAS property,
<emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis> in the
OF device tree, which describes how much space is required to store dump
data for the firmware provided dump sections, where the firmware defined
dump sections are:</para>

<itemizedlist>
<listitem>
<para>0x0001 = CPU State Data</para>
</listitem>

<listitem>
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> The platform must present the RTAS property,
<emphasis role="bold"><literal>&#8220;ibm-configure-kernel-dump-version&#8221;</literal></emphasis> in
the OF device tree.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
Option:</emphasis> After a dump registration is disabled (for example, by
a partition migration operation), calls to
<emphasis>ibm,os-term</emphasis> must return to the OS as though a dump
was not registered.</para>
<para>
<emphasis role="bold">Programming Note:</emphasis> The intended flow of interactions
that utilize this call is as follows:</para>

<orderedlist>
<listitem>
<para>The OS registers sections of memory for dump preservation during
OS initialization</para>
</listitem>

<listitem>
<para>The OS terminates abnormally</para>
</listitem>

<listitem>
<para>The Platform moves registered sections of memory as instructed
during dump registration.</para>
</listitem>

<listitem>
<para>The Partition reboots and provides the prior registration data
in the device tree.</para>
</listitem>

<listitem>
<para>The OS writes the preserved memory regions to disk before using
those memory regions for regular use</para>
</listitem>

<listitem>
<para>The OS completes/invalidates current dump status.</para>
</listitem>

<listitem>
<para>The OS must use H_CLEAR_HPT to clear the page table if running
in XIVE Exploitation Mode, H_REMOVE is not a sufficient mechanism
to clear the HPT. Failure to use H_CLEAR_HPT may result in H_READ
returning invalid entries as valid.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>

</section>

1097
LoPAR/sec_rtas_dma_window.xml
View File

File diff suppressed because it is too large Load Diff

287
LoPAR/sec_rtas_get_dynamic_sensor_state.xml
Unescape Escape View File

@ -1,287 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_61055">
<title><emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call</title>
<para>This RTAS call behaves as the RTAS
<emphasis>get-sensor-state</emphasis> call, except that the instance of
the sensor is identified by a location code instead of a index.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569332_54151">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms that
implement any sensors that are identified by location code instead of
index (see Requirement
<xref linkend="dbdoclet.50569332_80480" />) must implement the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS function.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,get-dynamic-sensor-state</emphasis> must implement the
argument call buffer defined by
<xref linkend="dbdoclet.50569332_71500" />.</para>
<para>&#160;</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_71500">
<title><emphasis>ibm,get-dynamic-sensor-state</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-dynamic-sensor-state</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Sensor</emphasis>
</para>
</entry>
<entry>
<para>Token defining the sensor</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>Location Code Address</emphasis>
</para>
</entry>
<entry>
<para>Real or Logical address of a location code string, in the
format defined by Requirement
<xref linkend="dbdoclet.50569332_75857" /></para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy, try again later</para>
<para>-3: No such indicator</para>
<para>0: Success</para>
<para>990x: Extended delay, where x is a number between 0 and
5, as described below</para>
</entry>
</row>
<row>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>State</emphasis>
</para>
</entry>
<entry>
<para>Current state of the sensor as defined in the
<emphasis>Defined Values</emphasis> column of
<xref linkend="dbdoclet.50569332_23534" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the power
<emphasis>x</emphasis> milliseconds (where
<emphasis>x</emphasis> is the last digit of the 990x return code), before
calling
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with the same indicator
type and location code. However, software may call
<emphasis>ibm,get-dynamic-sensor-state</emphasis> again either earlier or
later than this.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>ibm,get-dynamic-sensor-state</emphasis> with a different sensor
until a non-busy return
<emphasis>Status</emphasis> has been received from the previous
<emphasis>ibm,get-dynamic-sensor-state</emphasis> call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The work area must be contiguous in real
memory and must reside below 4GB.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569332_75857">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>The input data
format in the work area must be as follows:</para>

<orderedlist numeration="loweralpha">
<listitem>
<para>32-bit integer length of the location code string, including
NULL</para>
</listitem>

<listitem>
<para>Location code string, NULL terminated, identifying the sensor to
be set.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The platform must not modify the location
code string.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The OS must only use this call with sensors
which have been provided by the
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
0xFFFFFFFF.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>The platform must use the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS call only for
dynamic sensor types of 9004, 9006 and 9007.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_61055"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>A <emphasis>Status</emphasis> of -3 must be returned for the following
conditions:</para>

<orderedlist numeration="loweralpha">
<listitem>
<para>Sensor type not supported</para>
</listitem>

<listitem>
<para>The specified location code does not identify a valid
sensor</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>

</section>

454
LoPAR/sec_rtas_get_indices.xml
Unescape Escape View File

@ -1,454 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="sec_get_indices_rtas_call">

<title><emphasis>ibm,get-indices</emphasis> Call</title>

<para>The RTAS function
<emphasis>ibm,get-indices</emphasis> is used to obtain the indices and
location codes for a specified indicator or sensor token. It allows for
obtaining the list of indicators and sensors dynamically and therefore
assists in any Dynamic Reconfiguration operation that involves indicators
and sensors being added or deleted from the platform (unlike the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>,
and <emphasis role="bold"><literal>&#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).
This call also allows discontiguous indices for a particular indicator or
sensor type (unlike the
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>
&#8220;ibm,environmental-sensor&#8221;</literal></emphasis> properties).</para>
<para>This RTAS call is not used for DR indicators (9001, 9002, and 9003)
or DR sensors (9003). See the following sections in the DR chapter for more
information:
<xref linkend="dbdoclet.50569342_85040" /> and
<xref linkend="dbdoclet.50569342_61130" />.</para>
<para>It may require several calls to the
<emphasis>ibm,get-indices</emphasis> RTAS routine to get the entire list of
indicators or sensors of a particular type. Each call may specify a
different work area.</para>
<para>The OS may not interleave calls to
<emphasis>ibm,get-indices</emphasis> for different indicator or sensor
types. Other standard RTAS locking rules apply.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The RTAS function
<emphasis>ibm,get-indices</emphasis> must implement the argument call buffer
defined by
<xref linkend="dbdoclet.50569332_50675" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_50675">
<title><emphasis>ibm,get-indices</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="7" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-indices</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator or Sensor</emphasis>
</para>
</entry>
<entry>
<para>0: indicator of given type</para>
<para>1: sensor of given type</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator Type</emphasis>
</para>
</entry>
<entry>
<para>Indicator or sensor type (for example, 9006, 9007)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>Address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Starting Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing first indicator number to
return</para>
</entry>
</row>
<row>
<entry morerows="1" valign="middle">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-3: Indicator type not supported</para>
<para>-4: Optional: Indicator list changed, start again</para>
<para>0: Success</para>
<para>1: More data available; call again</para>
<para>990x:Extended Delay where x is a number 0-5 (see text
below)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Starting Number</emphasis>
</para>
</entry>
<entry>
<para>Integer to use as the Starting Number parameter on the next
call, or 1 if no more calls are required</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When the 990x
<emphasis>Status</emphasis> is returned, it is suggested that software delay
for 10 raised to the x milliseconds (where x is the last digit of the 990x
return code), before calling
<emphasis>ibm,get-indices</emphasis> with the same Starting Number and
Indicator Type. However, software may issue the
<emphasis>ibm,get-indices</emphasis> call again either earlier or later than
this.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The OS must not interleave calls to
<emphasis>ibm,get-indices</emphasis> for different indicator or sensor
types.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>On the first call to get a particular
<emphasis>Indicator Type</emphasis>, the caller must provide a Starting
Number of 1 (32-bit integer)</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>When
<emphasis>ibm,get-indices</emphasis> is called with a Starting Number of 1,
firmware must refresh any stale data in previously cached firmware buffers
for that indicator (for example, data made stale by a Dynamic
Reconfiguration operation).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>When calling
<emphasis>ibm,get-indices</emphasis> with a Starting Number of 1, a
previously returned
<emphasis>Next Starting Number</emphasis> value must be discarded.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Optionally, if firmware detects a change in
the indicator list before the entire list is returned, the
<emphasis>ibm,get-indices</emphasis> call must return a -4 and the caller
must start again with a Starting Number of 1.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The return data format in the work area for
all sensors and indicators must be as follows:</para>

<itemizedlist>
<listitem>
<para>Number Returned: 32-bit integer representing the number of
indicator indices returned on this call</para>
</listitem>

<listitem>
<para>Sets of (32-bit integer index, 32-bit integer length of location
code including NULLs, location code string (NULL terminated and padded to
nearest 4 byte boundary)), one set per indicator or sensor, with the number
of sets indicated by the first integer in this work buffer</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>If the
<emphasis>Status</emphasis> returned is 1 (more data available, call again),
then the caller must call
<emphasis>ibm,get-indices</emphasis> again with the
<emphasis>Starting Number</emphasis> parameter set to the Next Starting
Number integer from the previously returned buffer.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must return the
<emphasis>Status</emphasis> value of -3 for the following conditions:</para>

<orderedlist numeration="loweralpha">
<listitem>
<para>Indicator type not supported</para>
</listitem>

<listitem>
<para>No indicators of specified Indicator Type available to
caller</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>If the <emphasis>ibm,get-indices</emphasis> RTAS call returns a
<emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
caller must consider that the contents of the work area is not
defined.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>The work area specified in the
<emphasis>ibm,get-indices</emphasis> RTAS call argument buffer must be
contiguous in logical real memory and must reside below 4GB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must only return the
indicator or sensor indices to which the caller has authorized access at
the time of the call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,get-indices</emphasis> RTAS call must make no assumptions
about the contents of the work area on the beginning of the call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>When the platform supports the
<emphasis>ibm,get-indices</emphasis> RTAS call, the device tree must include
the
<emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property
in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting
indicator information and must include the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property in
the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node if the call is to be used for getting sensor
information.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>When an indicator token is provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-indicator-indices-types&#8221;</literal></emphasis> property,
it must not be included in the
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis><literal>,indicator-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
property and must not be included in the
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para>When a sensor token is provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property, it
must not be included in the
<emphasis role="bold"><literal>&#8220;</literal></emphasis><emphasis><literal>&lt;vendor&gt;</literal></emphasis><emphasis role="bold"><literal>,sensor-</literal></emphasis><emphasis><literal>&lt;token&gt;</literal></emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis>
property and must not be included in the
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para>When an environmental sensor token is
provided in the
<emphasis role="bold"><literal>&#8220;ibm,get-sensor-indices-types&#8221;</literal></emphasis> property,
users of data in the
<emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis> property for
that sensor token must not assume that the indices are contiguous for that
sensor token (that is, any of the indices between 0 and the maxindex,
inclusive, may be missing).</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569332_80480">
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para>When the value of
any index returned is 0xFFFFFFFF, the OS must use the
<emphasis>ibm,get-dynamic-sensor-state</emphasis> and
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS functions for this
sensor or indicator, using the location code to identify the sensor or
indicator.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_get_indices_rtas_call"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>get-sensor-state</emphasis> or
<emphasis>get-indicator</emphasis> with an index value of 0xFFFFFFFF.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

408
LoPAR/sec_rtas_get_vpd.xml
Unescape Escape View File

@ -1,408 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_72964">
<title><emphasis>ibm,get-vpd</emphasis> RTAS Call</title>
<para>This RTAS call allows for collection of VPD that changes after OS
boot time (after the initial reporting in the OF device tree). When this
call is implemented, there is no overlap between what is reported in the
device tree and what is reported with this RTAS call. Also, when this
RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
is dynamically changed during OS run time is reported with this call and
not via the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property in the OF device
tree.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For all Dynamic Reconfiguration options
except PCI Hot Plug, when the platform VPD can change dynamically due to
a Dynamic Reconfiguration operation, the platform must implement the
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,get-vpd</emphasis> must implement the argument call buffer
defined by
<xref linkend="dbdoclet.50569332_62393" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_62393">
<title><emphasis>ibm,get-vpd</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="6" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,get-vpd</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Pointer to Location Code</emphasis>
</para>
</entry>
<entry>
<para>Real address of NULL-terminated string, contiguous in
real memory and below 4GB, which is the location code of the
FRU for which to obtain the VPD. When this parameter references
a NULL string the VPD for all location codes is
returned.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>Address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the sequence number of the call.
First call in sequence starts with 1, following calls (if
necessary) use the
<emphasis>Next Sequence Number</emphasis> returned from the
previous call.</para>
</entry>
</row>
<row>
<entry morerows="2" valign="middle">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-3: Parameter error</para>
<para>-4: Optional: VPD changed, start again</para>
<para>0: Success</para>
<para>1: More data available; call again</para>
<para>990x: Extended Delay where x is a number 0-5 (see text
below)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Return this integer as the
<emphasis>Sequence Number</emphasis> parameter on the next call
to continue the sequence, or 1 if no more calls are
required</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Bytes Returned</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the number of valid bytes returned
in the work area.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When the 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
the 990x return code), before calling
<emphasis>ibm,get-vpd</emphasis> with the same input parameters. However,
software may issue the
<emphasis>ibm,get-vpd</emphasis> call again either earlier or later than
this.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>On the first call to
<emphasis>ibm,get-vpd</emphasis> for a particular VPD gathering operation,
the caller must provide a
<emphasis>Sequence Number</emphasis> of 1 (32-bit integer)</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Upon calling
<emphasis>ibm,get-vpd</emphasis> with a
<emphasis>Sequence Number</emphasis> of 1, a previously returned
<emphasis>Next Sequence Number</emphasis> must be discarded. This means
that multiple calls to
<emphasis>ibm,get-vpd</emphasis> cannot be interleaved by multiple
processors, and if processor &#8220;B&#8221; starts a new
<emphasis>ibm,get-vpd</emphasis> sequence while processor &#8220;A&#8221;
has a call sequence in process (that is, the function on processor
&#8220;A&#8221; has returned a
<emphasis>Status</emphasis> of 1, and the subsequent call has not yet been
made) then the call sequence on processor &#8220;A&#8221; is
abandoned.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Optionally, if firmware detects a change in
the VPD being requested before the entire VPD is returned, the
<emphasis>ibm,get-vpd</emphasis> call must return a
<emphasis>Status</emphasis> of -4 and the caller must start again with a
Starting Number of 1.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> The platform should not impede
forward progress by continuously returning a
<emphasis>Status</emphasis> of -4.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The return data format in the work area
must be such that after returning all the data and concatenating all data
together in the order received, that the data is the same as is obtained
from the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property of the OF device
tree.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>Each stanza of the returned data must
include the YL (location code) keyword.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then the
platform must not provide the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> properties in the OF
device tree
<emphasis>root</emphasis> node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then any VPD
which may change after OS boot must be reported via the
<emphasis>ibm,get-vpd</emphasis> RTAS call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>If the
<emphasis>Status</emphasis> returned is 1 (more data available, call
again), then the caller must call
<emphasis>ibm,get-vpd</emphasis> again with the
<emphasis>Sequence Number</emphasis> parameter set to the
<emphasis>Next Sequence Number</emphasis> integer from the previously
returned call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>If a
<emphasis>Status</emphasis> of anything other than 0 or 1 is returned, the
contents of the work area is not defined.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The work area must be contiguous in real
memory and must reside below 4GB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>Firmware cannot count on the contents of
the work area at the beginning of any call to
<emphasis>ibm,get-vpd</emphasis> (regardless of the value of the
<emphasis>Sequence Number</emphasis>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>The location code referenced by the
<emphasis>Pointer to Location Code</emphasis> parameter must reside in
contiguous real memory below an address of 4GB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_72964"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>If the
<emphasis>ibm,get-vpd</emphasis> RTAS call is implemented, then firmware
must supply the
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node, the value of which is a single cell,
encoded as with
<emphasis>encode-int</emphasis>, which is the estimated maximum size in
bytes of the VPD that is returned if the
<emphasis>Pointer to Location Code</emphasis> parameter to the
<emphasis>ibm,get-vpd</emphasis> RTAS function is NULL (that is, all
system VPD). This size should take in to account possible concurrent
addition of new platform elements after the partition is started. If
firmware is unable to estimate this size, it may return a value of 0x0 to
indicate that no estimate is available.</para>
<para>
<emphasis role="bold">Software Implementation Notes:</emphasis>
</para>

<orderedlist>
<listitem>
<para>An OS should be prepared for older versions of firmware where
the
<emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis> property is not
provided.</para>
</listitem>

<listitem>
<para>Each stanza of the returned data must include the YL (location
code) keyword.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>

</section>

266
LoPAR/sec_rtas_lpar_perftools.xml
Unescape Escape View File

@ -1,266 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_26596">
<title><emphasis>ibm,lpar-perftools</emphasis> RTAS Call</title>

<para>This RTAS call provides access to platform-level facilities for
performance tools running in a partition on an LPAR system. Platforms may
require platform-specific tools, beyond the scope of this architecture,
to make this call available.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> The platform
must implement the LPAR option.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> RTAS must
implement the
<emphasis>ibm,lpar-perftools</emphasis> call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_48993" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_48993">
<title><emphasis>ibm,lpar-perftools</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="7" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,lpar-perftools</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Subfunction</emphasis>
</para>
</entry>
<entry>
<para>1: Convert hypervisor IAR value to method name.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address High</emphasis>
</para>
</entry>
<entry>
<para>Most significant 32 bits of real address of work
area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address Low</emphasis>
</para>
</entry>
<entry>
<para>Least significant 32 bits of real address of work
area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Size</emphasis>
</para>
</entry>
<entry>
<para>Size of work area in bytes</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Integer representing the sequence number of this call.
First call in sequence starts with 1, following calls (if
necessary) use the
<emphasis>Next Sequence Number</emphasis> returned from the
previous call.</para>
</entry>
</row>
<row>
<entry morerows="1" valign="middle">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error (Subfunction invalid, invalid work
area address, invalid work area size)</para>
<para>-9002: Partition does not have authority to perform this
function</para>
<para>-5: Buffer was too small to supply requested data</para>
<para>0: Success</para>
<para>990x: Extended delay</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Next Sequence Number</emphasis>
</para>
</entry>
<entry>
<para>Return this integer as the
<emphasis>Sequence Number</emphasis> parameter on the next call,
or 1 if no more calls are required.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
the 990x return code), before calling the
<emphasis>ibm,lpar-perftools</emphasis> call with the same input
parameters. However, software may issue the
<emphasis>ibm,lpar-perftools</emphasis> call again earlier or later than
this.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> For
<emphasis>subfunction</emphasis> value 1, on input the first 8 bytes of
the work area must contain the hypervisor IAR address to be converted. On
output, the first 8 bytes of the work area contain the offset of this
address from the start of the hypervisor function, method or module,
followed by a NULL-terminated text string containing the name of the
hypervisor function, method or module. If the address is not a valid
address in the hypervisor, on output the buffer must contain 0x0 (8
bytes) followed by a NULL-terminated text string indicating that the
address was not valid.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool support option:</emphasis> The work
area must reside in contiguous memory.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> If a
<emphasis>Status</emphasis> of anything other than 0 is returned, the
contents of the work area are not defined.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_26596"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Performance Tool Support option:</emphasis> A partition
must have at most one call to this function in process at a given time.
This means that if one processor in the partition initiates this call,
receives a Busy or Extended Delay return, and then another processor
calls this function with a sequence number of 1, a subsequent call using
the
<emphasis>Next Sequence Number</emphasis> returned to the first processor
results in a Parameter Error return code.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

262
LoPAR/sec_rtas_manage_storage_preservation.xml
Unescape Escape View File

@ -1,262 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_28221">
<title>ibm,manage-storage-preservation</title>

<para>Platforms may optionally preserve selected regions of storage
(LMBs) across client program boot cycles.
<xref linkend="dbdoclet.50569327_70628" /> for more information.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must implement the
<emphasis>ibm,manage-storage-preservation</emphasis> RTAS argument call
buffer as defined by
<xref linkend="dbdoclet.50569332_95221" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_95221">
<title><emphasis>ibm,manage-storage-preservation</emphasis> Argument Call
Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="5" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,manage-storage-preservation</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Subfunction</emphasis>
</para>
</entry>
<entry>
<para>0 = unused (return -3)</para>
<para>1 = Register specified LMB for preservation</para>
<para>2 = Query preservation state of specified LMB</para>
<para>3 = Deregister for preservation Specific LMB</para>
<para>4 = Deregister for preservation all caller&#8217;s
LMBs.</para>
<para>All other values reserved (return -3)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Reg High</emphasis>
</para>
</entry>
<entry>
<para>The high order 32 bits of the LMB's
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
1-3)</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Reg Low</emphasis>
</para>
</entry>
<entry>
<para>The low order 32 bits of the LMB's
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
1-3)</para>
</entry>
</row>
<row>
<entry morerows="1" valign="middle">
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy</para>
<para>-3: Parameter error (Subfunction or Reg invalid; or Reg
for a non-preservable LMB)</para>
<para>0: Success</para>
<para>990x: Extended delay where x is a number 0-5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Preservation state</emphasis>
</para>
</entry>
<entry>
<para>If
<emphasis>Status</emphasis>= Success, the current preservation
state of specified LMB (Subfunctions 1-3)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must include the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property in the
<emphasis>/memory</emphasis> nodes of its OF device tree, containing a
value which reflects the platform's ability to preserve the specific
LMB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The value of the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
LMB must be 0 (cannot be preserved).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must not preserve the first LMB, thus must indicate a value of 0 for the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
LMB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
must include the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property in the
<emphasis>/memory</emphasis> nodes of its OF device tree, valued to
reflect the platform's preservation state of the specific LMB.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
a reboot, must include in the OF
<emphasis role="bold"><literal>/rtas</literal></emphasis> node the
<emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis> property if the
previous client program registered one or more of its LMBs for
preservation.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> If the client
program registered an LMB for preservation, the platform must preserve
the LMB's storage state across client program reboots.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
a reboot, must include in the OF
<emphasis role="bold"><literal>/rtas</literal></emphasis> node the
<emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis> property
which reflects the value of the partition shutdown configuration
variable, and if this property is not present, a value of 0 must be
assumed by the OS.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

277
LoPAR/sec_rtas_set_dynamic_indicator.xml
Unescape Escape View File

@ -1,277 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_30542">
<title><emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call</title>

<para>This RTAS call behaves as the RTAS
<emphasis>set-indicator</emphasis> call, except that the instance of the
indicator is identified by a location code instead of a index.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569332_58519">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms that
implement any indicators that are identified by location code instead of
index (see Requirement
<xref linkend="dbdoclet.50569332_80480" />) must implement the
<emphasis>ibm,set-dynamic-indicator</emphasis> RTAS function.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The RTAS function
<emphasis>ibm,set-dynamic-indicator</emphasis> must implement the argument
call buffer defined by
<xref linkend="dbdoclet.50569332_14870" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_14870">
<title><emphasis>ibm,set-dynamic-indicator</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">
<emphasis>Name</emphasis>
</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="5" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,set-dynamic-indicator</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Indicator</emphasis>
</para>
</entry>
<entry>
<para>Token defining the indicator</para>
<para>9006: Error Log</para>
<para>9007: Identify Indicator</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>State</emphasis>
</para>
</entry>
<entry>
<para>Desired new state; see
<xref linkend="dbdoclet.50569332_32237" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Location Code Address</emphasis>
</para>
</entry>
<entry>
<para>Real or Logical address of a location code string, in the
format defined by Requirement
<xref linkend="dbdoclet.50569332_69341" /></para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware error</para>
<para>-2: Busy, try again later</para>
<para>-3: No such indicator</para>
<para>0: Success</para>
<para>990x: Extended delay, where x is a number between 0 and
5, as described below</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>When 990x
<emphasis>Status</emphasis> is returned, it is suggested that software
delay for 10 raised to the power
<emphasis>x</emphasis> milliseconds (where
<emphasis>x</emphasis> is the last digit of the 990x return code), before
calling
<emphasis>ibm,set-dynamic-indicator</emphasis> with the same indicator
type and location code. However, software may call
<emphasis>ibm,set-dynamic-indicator</emphasis> again either earlier or
later than this.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OS must not call
<emphasis>ibm,set-dynamic-indicator</emphasis> with a different indicator
until a non-busy return
<emphasis>Status</emphasis> has been received from the previous
<emphasis>ibm,set-dynamic-indicator</emphasis> call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>The location code string referenced by the
<emphasis>Location Code Address</emphasis> argument in the
<emphasis>ibm,set-dynamic-indicator</emphasis> argument call buffer must
reside in contiguous in real memory below an address of 4GB.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569332_69341">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>The input data
format in the work area must be as follows:</para>

<orderedlist numeration="loweralpha">
<listitem>
<para>32-bit integer length of the location code string, including
NULL</para>
</listitem>

<listitem>
<para>Location code string, NULL terminated, identifying the sensor to
be set.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>The platform must not modify the location
code string.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>The OS must only use this call for
indicators which have been provided by the
<emphasis>ibm,get-indices</emphasis> RTAS call with an index value of
0xFFFFFFFF.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>Platforms must identify all indicators
except types 9006 and 9007 by index.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_30542"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS call must return A
<emphasis>Status</emphasis> of -3 for the following conditions:</para>

<orderedlist numeration="loweralpha">
<listitem>
<para>Indicator type not supported</para>
</listitem>

<listitem>
<para>The specified location code does not identify a valid
indicator</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>

</section>

671
LoPAR/sec_rtas_suspend_me.xml
Unescape Escape View File

@ -1,671 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_45918">
<title><emphasis>ibm,suspend-me</emphasis> RTAS Call</title>
<para>The
<emphasis>ibm,suspend-me</emphasis> RTAS call provides the calling OS the
ability to suspend processing. Suspension of processing is required as
part of OS hibernation or migration to another platform. This RTAS call
is made by the last active processor thread of a partition. The OS uses
the H_JOIN hcall() (see
<xref linkend="dbdoclet.50569344_15933" />) to deactivate other
processing threads. Processing treads may exit H_JOIN due to an
unmaskable interrupt; if a thread has exited H_JOIN,
<emphasis>ibm,suspend-me</emphasis> fails with a status of &#8220;multiple
processor threads active&#8221;. The wake up from suspension is triggered
by partition state change (see
<xref linkend="sec_vasi_partition_migration" /> and
<xref linkend="sec_vasi_partition_hibernation" />). The
<emphasis>ibm,suspend-me</emphasis> RTAS call returns only on the calling
virtual processor. Other virtual processors that were inactive when
<emphasis>ibm,suspend-me</emphasis> was called remain so until they are
proded by the OS.</para>
<para>While the logical configuration of a suspended partition remains
static, the physical properties may change; the OS may wish to issue
<emphasis>ibm,update-nodes</emphasis> (see
<emphasis>
<xref linkend="dbdoclet.50569332_84414" />) to determine if any device
tree nodes changed, and then</emphasis> refresh its view of the device
tree physical properties using
<emphasis>ibm,update-properties</emphasis> (see
<xref linkend="dbdoclet.50569332_40069" />) and/or
<emphasis>ibm,configure-connector</emphasis> (see
<xref linkend="dbdoclet.50569342_39636" />). Also during suspension, some
system parameters may have changed. See
<xref linkend="dbdoclet.50569332_10519" />, for details. The OS may want
to re-scan selected system parameters.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the Logical Partitioning option (see
<xref linkend="dbdoclet.50569344_14591" />)
<emphasis>.</emphasis></para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> RTAS must
implement the
<emphasis>ibm,suspend-me</emphasis> call within a logical partition using
the argument call buffer defined by
<xref linkend="dbdoclet.50569332_91600" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_91600">
<title><emphasis>ibm,suspend-me</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="2" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,suspend-me</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>9000: Suspension Aborted</para>
<para>0: Success -- expected return on function resume</para>
<para>-1: Hardware Error</para>
<para>&#160;</para>
<para>-9004: Partition not suspendable</para>
<para>-9005: Multiple processor threads active</para>
<para>-9006: Outstanding COP Operations</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition is in the &#8220;suspendable state&#8221;, else return
a status of -9004 &#8220;Partition not suspendable&#8221;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition has no other active processor thread, else return a
status of -9005 &#8220;Multiple processor threads active&#8221;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the Thread Join option (see
<xref linkend="dbdoclet.50569344_90755" />).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must restore all partition state as of the time of the call to
<emphasis>ibm,suspend-me</emphasis> prior to returning from the
<emphasis>ibm,suspend-me</emphasis> RTAS call, except for the values of
those Open Firmware Device tree properties as reported using the Update
OF Tree option, and the system parameters given in
<xref linkend="dbdoclet.50569332_10519" />.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must be prepared to respond to OS requests for updated device tree
information immediately after returning from the
<emphasis>ibm,suspend-me</emphasis> RTAS call.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must support the &#8220;update OF tree&#8221; option.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must support the &#8220;Partner partition suspended&#8221; CRQ Transport
Event (See
<xref linkend="dbdoclet.50569348_93265" />).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
deliver &#8220;Partner partition suspended&#8221; CRQ Transport Events to
both CRQs of all CRQ connections associated with the partition calling
<emphasis>ibm,suspend-me.</emphasis></para>
<para><emphasis role="bold">Note:</emphasis> The transport events are visible to the partition calling
<emphasis>ibm,suspend-me</emphasis> after the subsequent resume from
suspension, while the transport events are immediately visible to the
partner partitions of the caller at the time of the suspend.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must cause the platform to
set the state of all of the caller&#8217;s CRQs to disabled.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the H_ENABLE_CRQ hcall() using the syntax and semantics
described in
<xref linkend="dbdoclet.50569348_43427" />.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For platforms that implement the Partition Suspension and VSCSI
options:</emphasis> The
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property of the
platform&#8217;s
<emphasis>v-scsi</emphasis> and
<emphasis>v-scsi-host</emphasis> nodes must include
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-2&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;IBM,v-scsi-host-2&#8221;</literal></emphasis> respectively
indicating the platform supports the &#8220;Partner partition
suspended&#8221; CRQ Transport Event.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> If the OS is
participating in OS surveillance, to avoid a surveillance time out, the
OS must disable surveillance (see
<xref linkend="dbdoclet.50569332_60143" />) prior to calling
<emphasis>ibm,suspend-me</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must implement the LRDR option (See
<xref linkend="dbdoclet.50569342_75053" />).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The logical
configuration of a partition, including its view of the
<emphasis>rtas-display-device</emphasis>, and rtas tone facility must not
change while a partition is suspended.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must not change the support for a system parameter during
suspension.</para>
<para>
<emphasis role="bold">NOTE:</emphasis> If RTAS returns a status of -3 (System
parameter not supported) prior to suspension, it returns a Status of -3
for accesses to that same system parameter after suspension. Similarly if
RTAS does not return a Status of -3 prior to suspension for a given
system parameter, it does not do so after suspension.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must limit the system parameters that change values during suspension to
those specified in
<xref linkend="dbdoclet.50569332_10519" /> (all system parameters not
specified are preserved).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
must preserve up to the first 32 SLB entries for each partition processor
during the suspension. Other SLB entries are subject to loss.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_45918"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Partition Suspension option with the Platform
Facilities Option:</emphasis> The
<emphasis>ibm,suspend-me</emphasis> RTAS call must determine that the
calling partition has no outstanding coprocessor operations else return a
status of -9005 &#8220;Outstanding COP Operations&#8221;.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_10519">
<title>System Parameters that May Change During Partition
Migration and Hibernation</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">System Parameter Token</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">&#160;</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>0-15</para>
</entry>
<entry>
<para>HMC</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>18-19</para>
</entry>
<entry>
<para>Legacy processor CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>20</para>
<para>&#160;</para>
</entry>
<entry>
<para>SPLPAR characteristics</para>
</entry>
<entry>
<para>Only specified SPLPAR keywords may change value</para>
</entry>
</row>
<row>
<entry morerows="6" valign="middle">
<para>&#160;</para>
</entry>
<entry>
<para>DesiredEntitledCapacity</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredMemory</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredNumberOfProcessors</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DesiredVariableCapacityWeight</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>DispatchWheelRotationPeriod</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>MinimumEntitledCapacityPerVP</para>
</entry>
<entry>
<para>Platform prevents migration where current Entitled
Capacity/VCPU ratio would be below the target's minimum.</para>
</entry>
</row>
<row>
<entry>
<para>MaximumPlatformProcessors</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>22</para>
</entry>
<entry>
<para>platform_auto_power_restart</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>23</para>
</entry>
<entry>
<para>sp-remote-pon</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>24</para>
</entry>
<entry>
<para>sp-rb4-pon</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>25</para>
</entry>
<entry>
<para>sp-snoop-str</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>30</para>
</entry>
<entry>
<para>sp-call-home</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>31</para>
</entry>
<entry>
<para>sp-current-flash-image</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>33</para>
</entry>
<entry>
<para>epow3-quiesce-time</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>34</para>
</entry>
<entry>
<para>memory-preservation-boot-time</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>35</para>
</entry>
<entry>
<para>SCSI initiator identifier</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>36</para>
</entry>
<entry>
<para>AIX support</para>
</entry>
<entry>
<para>The keyword &#8220;support&#8221; may not change to the
value &#8220;no&#8221; for an AIX client.</para>
</entry>
</row>
<row>
<entry>
<para>37</para>
</entry>
<entry>
<para>enhanced processor CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>38</para>
</entry>
<entry>
<para>enhanced memory CoD</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>39</para>
</entry>
<entry>
<para>CoD Options</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>41</para>
</entry>
<entry>
<para>firmware boot options</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>43</para>
</entry>
<entry>
<para>processor module information</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>

</section>

828
LoPAR/sec_rtas_update_nodes.xml
Unescape Escape View File

@ -1,828 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569332_84414">
<title><emphasis>ibm,update-nodes</emphasis> RTAS Call</title>

<para>This RTAS call is used to determine which device tree nodes have
changed due to a massive platform reconfiguration such as when the
partition is migrated between machines. Differing platform
reconfigurations are expected to potentially result in different sets of
nodes being updated; the &#8220;scope&#8221; argument communicates what
set of changes are to be reported. The work area is a 4 KB naturally
aligned area of storage below the first 4 GB; as such, it may not be
large enough to contain the reports of all changed nodes. The status
value of 1 is used to inform the caller that there are more updates to
report and that it will have to call the
<emphasis>ibm,update-nodes</emphasis> RTAS again to receive them. On
subsequent calls the state variable, which is set to zero on the first
call, is set to the value returned on the previous call, to supply RTAS
with the information it needs to continue from where the previous call
ended.</para>
<para>Upon return, the work area contains, in addition to the state
variable, zero or more operation lists, and logically ends with a
terminator (4 byte word naturally aligned containing 0x00000000). An
operation list consists of an operator (4 bytes naturally aligned) and
zero or more (up to a the maximum number of 4 byte locations remaining in
the work area) operands, each 4 bytes long. An operator consists of a
single byte opcode followed by 3 bytes encoded with the binary value of
the number of operands that follow. An operator with an operand length
field of zero performs no operation, and the opcode of zero is reserved
for the terminator -- thus the terminator can be considered a special
encoding of a no-op operator.</para>

<itemizedlist>
<listitem>
<para>The opcode of 0x01 is used for deleted nodes -- the operands are
the
<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
</listitem>

<listitem>
<para>The opcode of 0x02 is used for updated nodes -- the operands are
the
<emphasis role="bold">phandle</emphasis> values for the updated nodes. The updated
properties are obtained using the
<emphasis>ibm,update-properties</emphasis> RTAS call.</para>
</listitem>

<listitem>
<para>The opcode of 0x03 is used for adding nodes -- the operands are
pairs of
<emphasis role="bold">phandle</emphasis> and
<emphasis role="bold">drc-index</emphasis> values; the
<emphasis role="bold">phandle</emphasis> value denotes the parent node of the node to
be added and the
<emphasis role="bold">ibm,drc-index</emphasis> value is passed with the
<emphasis>ibm,configure-connector</emphasis> RTAS call to obtain the
contents of the added node.</para>
</listitem>
</itemizedlist>

<para>To make processing of device tree updates simpler, all opcode 0x01
(delete) operations (if any) are presented prior to all opcode 0x02
(update) operations (if any), and finally any 0x03 (addition) operations
are presented. The
<emphasis role="bold">phandle</emphasis> operand values are the same
<emphasis role="bold">phandle</emphasis> values as reported by the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
include the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property in all OF nodes
specified in
<xref linkend="dbdoclet.50569332_80965" />.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Update OF Tree option:</emphasis> The platform must
implement the
<emphasis>ibm,update-nodes</emphasis> RTAS call using the argument call
buffer defined by
<xref linkend="dbdoclet.50569332_55185" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_55185">
<title><emphasis>ibm,update-nodes</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1*" align="center" />
<colspec colname="c2" colwidth="2*" align="center" />
<colspec colname="c3" colwidth="4*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="4" valign="middle">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,update-nodes</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work Area Address</emphasis>
</para>
</entry>
<entry>
<para>32 bit real address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Scope</emphasis>
</para>
</entry>
<entry>
<para>Values per
<xref linkend="dbdoclet.50569332_80965" />.</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-1: Hardware Error</para>
<para>-2: Busy</para>
<para>-3: Parameter Error (Purpose does not match the current
partition state)</para>
<para>0: Success</para>
<para>1: More nodes updated -- call again</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS call work area must be 4 KB
long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else
RTAS may return -3 &#8220;Parameter Error&#8221;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS for a given value of &#8220;
<emphasis>Scope</emphasis>&#8221; must be formatted as specified in
<xref linkend="dbdoclet.50569332_76526" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76526">
<title>Initial Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" align="center" />
<thead>
<row>
<entry>
<para>0x00000000 (State Variable indicates Initial call for
specified
<emphasis>Scope</emphasis>)</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>12 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Upon successful return (non-negative status
value) from
<emphasis>ibm,update-nodes</emphasis> the work area must by formatted as
defined in
<xref linkend="dbdoclet.50569332_64519" />. (Note each entry in
<xref linkend="dbdoclet.50569332_64519" /> is 4 bytes long.)</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64519">
<title>Format of Work Area for
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" align="center" />
<tbody valign="middle" >
<row>
<entry>
<para>State Variable (4 Bytes)</para>
</entry>
</row>
<row>
<entry>
<para>12 bytes of 0x00 (reserved)</para>
</entry>
</row>
<row>
<entry>
<para>0 or more operation lists</para>
</entry>
</row>
<row>
<entry>
<para>. . .</para>
</entry>
</row>
<row>
<entry>
<para>Terminator (0x00000000)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis>ibm,update-nodes</emphasis> RTAS call operation list for the
<emphasis>ibm,update-nodes</emphasis> RTAS call must contain an operator
(4 bytes naturally aligned) and zero or more 4 byte operands up to the
end of the work area.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>An operator in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
formatted with, starting at the high order byte, a single byte opcode
followed by 3 bytes encoded with the binary value of the number of
operands that follow.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>An operator in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list with an
operand length field of zero must be considered to perform no
operation.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The opcode of 0x01 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
used to denote node deletions.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para>The operands for opcode 0x01 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the

<emphasis role="bold">phandle</emphasis> values for the deleted nodes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para>The opcode of 0x02 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
used to denote updated nodes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para>The operands for opcode 0x02 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be the
<emphasis role="bold">phandle</emphasis> values for the updated nodes that may be used
as the
<emphasis>ibm,update-properties</emphasis> RTAS call argument to obtain
the changed properties of the updated node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para>The opcode of 0x03 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must used
for the added nodes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para>The operands for opcode of 0x03 in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list must be
<emphasis role="bold">phandle</emphasis> and
<emphasis role="bold">drc-index</emphasis> value pairs (each value being 4 bytes
on a natural boundary totalling 8 bytes for the pair) denoting the parent
node of the added node and the
<emphasis>ibm,configure-connector</emphasis> RTAS call argument to obtain
the contents of the added node respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para>All opcode 0x01 (delete) in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
must be presented prior to any opcode 0x02 (update) operations (if
any).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para>All opcode 0x02 (update) in an
<emphasis>ibm,update-nodes</emphasis> RTAS call operation list (if any)
must be presented prior to any opcode 0x03 (add) operations (if
any).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para>The work area on subsequent call(s) to
<emphasis>ibm,update-nodes</emphasis> RTAS for the same value of the
<emphasis role="bold"><literal>&#8220;Scope&#8221;</literal></emphasis> must be formatted as specified in
<xref linkend="dbdoclet.50569332_64422" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_64422">
<title>Format of Work Area for Subsequent Calls to
<emphasis>ibm,update-nodes</emphasis></title>
<tgroup cols="1">
<colspec colname="c1" colwidth="100*" align="center" />
<thead>
<row>
<entry>
<para>Value of the 1st 16 bytes of the returned work area from
last call to
<emphasis>ibm,update-nodes</emphasis> RTAS that returned status
of 1.</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Don&#8217;t Care . . .</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para>The &#8220;<emphasis>Scope</emphasis>&#8221; argument for the
<emphasis>ibm,update-nodes</emphasis> RTAS call must be one of the values
specified in the scope value column of
<xref linkend="dbdoclet.50569332_80965" />, else RTAS may return -3
&#8220;Parameter Error&#8221;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_84414"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para>For the
<emphasis>ibm,update-nodes</emphasis> RTAS call, the platform must
restrict its reported node updates to those specified in
<xref linkend="dbdoclet.50569332_80965" /> for the value of the specified
<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 valign="middle" >
<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">
<title>Nodes That May be Reported by
<emphasis>ibm,update-nodes</emphasis> for a Given Value of the
&#8220;<emphasis>Scope</emphasis>&#8221; Argument</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<thead>
<row>
<entry>
<para>Scope Value</para>
</entry>
<entry>
<para>Reportable node types (value of
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> property)</para>
</entry>
<entry>
<para>Supported Opcodes</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="7" valign="middle">
<para>Negative values: Platform Resource Reassignment events as
from
<emphasis>event-scan</emphasis> RTAS</para>
</entry>
<entry>
<para><emphasis role="bold">cpu</emphasis></para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">memory</emphasis></para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,plaform-facilities</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,random-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,compression-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,encryption-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry morerows="13" valign="middle">
<para>1 Partition Migration / Hibernation</para>
</entry>
<entry>
<para>
<emphasis role="bold">root</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">openprom</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">rtas</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">vdevice</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">cpu</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">cache</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">options</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">memory</emphasis>
</para>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">ibm,dynamic-reconfiguration-memory</emphasis></para>
</entry>
<entry>
<para>&lt;all&gt;</para>
</entry>
</row>
<row>
<entry>
<para><emphasis role="bold">ibm,platform-facilities</emphasis></para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,random-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,compression-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,encryption-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">ibm,memory-utilization_instrumentation-v#</emphasis>
</para>
</entry>
<entry>
<para>0x01-0x03</para>
</entry>
</row>
<row>
<entry>
<para>2 Activate Firmware</para>
</entry>
<entry>
<para>
<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>
</entry>
<entry>
<para>0x02</para>
</entry>
</row>
</tbody>
</tgroup>
</table>

</section>

1401
LoPAR/sec_rtas_update_properties.xml
View File

File diff suppressed because it is too large Load Diff

219
LoPAR/app_bibliography.xml → Platform/app_bibliography.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,7 +13,7 @@
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:xi="http://www.w3.org/2001/XInclude"
@ -22,230 +22,263 @@
xml:id="dbdoclet.50569387_27251">
<?dbhtml stop-chunking?>
<title> Bibliography</title>
<para>This section lists documents which were referenced in this specification or which provide
additional information, and some useful information for obtaining these documents. Referenced
documents are listed below. When any of the following standards are superseded by an approved
<para>This section lists documents which were referenced in this specification or which provide
additional information, and some useful information for obtaining these documents. Referenced
documents are listed below. When any of the following standards are superseded by an approved
revision, the revision shall apply.</para>
<orderedlist>
<!-- TODO: Uncomment documents needing referencing and comment out local document -->
<!--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>
<para><citetitle>Power ISA</citetitle><anchor xml:id="dbdoclet.50569387_99718"
xreflabel="Power ISA specification"/></para>
<para><anchor xml:id="LoPAR.DeviceTree"
xreflabel="Linux on Power Architecture Reference: Device Tree"/><citetitle>
Linux on Power Architecture Reference: Device Tree</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.Error"
xreflabel="Linux on Power Architecture Reference: Error Recovery and Logging"/><citetitle>
Linux on Power Architecture Reference: Error Recovery and Logging</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.Virtualization"
xreflabel="Linux on Power Architecture Reference: Virtualization"/><citetitle>
Linux on Power Architecture Reference: Virtualization</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.RTAS"
xreflabel="Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)"/><citetitle>
Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)</citetitle></para>
</listitem>
<!-- End TODO list -->

<listitem>
<para><anchor xml:id="dbdoclet.50569387_45524"
<para><citetitle>Power ISA</citetitle><anchor xml:id="dbdoclet.50569387_99718"
xreflabel="Power ISA specification"/></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_45524"
xreflabel="IEEE Open Firmware standard"/>
<citetitle>IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware:
<citetitle>IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware:
Core Requirements and Practices</citetitle></para>
<para>IEEE part number DS02683, ISBN 1-55937-426-8</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_14175"
<para><anchor xml:id="dbdoclet.50569387_14175"
xreflabel="IEEE Open Firmware Errata specification"/>
<citetitle>Core Errata, IEEE P1275.7/D4</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_31707"
<para><anchor xml:id="dbdoclet.50569387_31707"
xreflabel="Open Firmware TFTP extensions"/>
<citetitle>Open Firmware Recommended Practice:OBP-TFTP
<citetitle>Open Firmware Recommended Practice:OBP-TFTP
Extension</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_27008"
<para><anchor xml:id="dbdoclet.50569387_27008"
xreflabel="Open Firmware Device Support Extensions specification"/>
<citetitle>Open Firmware Recommended Practice: Device
<citetitle>Open Firmware Recommended Practice: Device
Support Extensions</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_22451"
<para><anchor xml:id="dbdoclet.50569387_22451"
xreflabel="PCI Bus Binding to Open Firmware standard"/>
<citetitle>PCI Bus binding to: IEEE Std 1275-1994, Standard
<citetitle>PCI Bus binding to: IEEE Std 1275-1994, Standard
for Boot (Initialization, Configuration) Firmware</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_40740"
<para><anchor xml:id="dbdoclet.50569387_40740"
xreflabel="Open Firmware Interrupt Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_33384"
<para><anchor xml:id="dbdoclet.50569387_33384"
xreflabel="Open Firmware Forth Source and FCode Image Support specification"/>
<citetitle>Open Firmware: Recommended Practice - Forth Source
<citetitle>Open Firmware: Recommended Practice - Forth Source
and FCode Image Support</citetitle>, Version 1.0</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_67880"
<para><anchor xml:id="dbdoclet.50569387_67880"
xreflabel="Open Firmware Interrup Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle>, Version 1.0</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_33177"
<para><anchor xml:id="dbdoclet.50569387_33177"
xreflabel="Open Firmware TFTP Booting extensions"/>
<citetitle>Open Firmware: Recommended Practice - TFTP Booting
<citetitle>Open Firmware: Recommended Practice - TFTP Booting
Extensions</citetitle>, Version 0.8</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_27351"
<para><anchor xml:id="dbdoclet.50569387_27351"
xreflabel="Open Firmware Interposition specification"/>
<citetitle>Open Firmware: Recommended Practice -
<citetitle>Open Firmware: Recommended Practice -
Interposition</citetitle>, Version 0.2</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_22601"
<para><anchor xml:id="dbdoclet.50569387_22601"
xreflabel="MS-DOS Programmer's Reference specification"/>
<citetitle>MS-DOS Programmer's Reference</citetitle></para>
<para>Published by Microsoft</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_18190"
<para><anchor xml:id="dbdoclet.50569387_18190"
xreflabel="Win32 Executable File Format article"/>
<citetitle>Peering Inside the PE: A Tour of the Win32 Portable
<citetitle>Peering Inside the PE: A Tour of the Win32 Portable
Executable File Format</citetitle></para>
<para>Found in the March, 1994 issue of <citetitle> Microsoft Systems Journal</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_85757"
<para><anchor xml:id="dbdoclet.50569387_85757"
xreflabel="CD-ROM Volume and File Structure standard"/>
<citetitle> ISO-9660, Information processing -- Volume and
<citetitle> ISO-9660, Information processing -- Volume and
file structure of CD-ROM for information interchange</citetitle></para>
<para>Published by International Organization for Standardization</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_38836"
<para><anchor xml:id="dbdoclet.50569387_38836"
xreflabel="System V Application Binary Interface, PowerPC Processor supplement"/>
<citetitle>System V Application Binary Interface, PowerPC
<citetitle>System V Application Binary Interface, PowerPC
Processor Supplement</citetitle></para>
<para>By Sunsoft<citetitle></citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_11453"
<para><anchor xml:id="dbdoclet.50569387_11453"
xreflabel="Standard Generalized Markup Language (SGML) standard"/>
<citetitle>ISO Standard 8879:1986, Information Processing
-- Text and Office Systems -- Standard Generalized Markup Language (SGML)</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_38891"
<para><anchor xml:id="dbdoclet.50569387_38891"
xreflabel="Personal Computer Back Plane Bus standard"/>
<citetitle>IEEE 996, A Standard for an Extended Personal Computer
<citetitle>IEEE 996, A Standard for an Extended Personal Computer
Back Plane Bus</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_65468"
<para><anchor xml:id="dbdoclet.50569387_65468"
xreflabel="PCI Local Bus specification"/>
<citetitle>PCI Local Bus Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the PCI SIG website
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_60429"
<para><anchor xml:id="dbdoclet.50569387_60429"
xreflabel="PCI-to-PCI Bridge Architecture specification"/>
<citetitle>PCI-to-PCI Bridge Architecture Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the
PCI SIG website for the most current version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_87046"
<para><anchor xml:id="dbdoclet.50569387_87046"
xreflabel="PCI Standard Hot-Plug Controller and Subsystem specification"/>
<citetitle>PCI Standard Hot-Plug Controller and Subsystem
<citetitle>PCI Standard Hot-Plug Controller and Subsystem
Specification</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_26550"
<para><anchor xml:id="dbdoclet.50569387_26550"
xreflabel="PCI-X Protocol addendum"/>
<citetitle>PCI-X Protocol Addendum to the PCI Local Bus Specification </citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI-X related components or platforms. See the PCI SIG website for the most
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI-X related components or platforms. See the PCI SIG website for the most
current version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_66784"
<para><anchor xml:id="dbdoclet.50569387_66784"
xreflabel="PCI Express Base specification"/>
<citetitle>PCI Express Base Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design PCI Express related components or platforms. See the PCI SIG website for
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design PCI Express related components or platforms. See the PCI SIG website for
the most current version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_28381"
<para><anchor xml:id="dbdoclet.50569387_28381"
xreflabel="PCI Express to PCI/PCI-X Bridge specification"/>
<citetitle>PCI Express to PCI/PCI-X Bridge Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express related components or platforms. See the PCI SIG website for the most current
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express related components or platforms. See the PCI SIG website for the most current
version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_34114"
<para><anchor xml:id="dbdoclet.50569387_34114"
xreflabel="System Management BIOS reference"/>
<citetitle>System Management BIOS (SMBIOS) Reference
<citetitle>System Management BIOS (SMBIOS) Reference
Specification</citetitle></para>
</listitem>

<!-- TODO: Are the following 3 items needed? -->
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>

<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>

<listitem>
<para><!-- anchor xml:id="dbdoclet.50569387_72648" xreflabel=""/ --><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_16481"
<para><anchor xml:id="dbdoclet.50569387_16481"
xreflabel="RS/6000 Product Topology Data System and Product Development guide"/>
<citetitle>IBM RS/6000&#174; Division, Product Topology Data System,
<citetitle>IBM RS/6000&#174; Division, Product Topology Data System,
Product Development Guide</citetitle></para>
<para>Version 2.1</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_94229"
<para><anchor xml:id="dbdoclet.50569387_94229"
xreflabel="Single Root I/O Virtualization and Sharing specification"/>
<citetitle>Single Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>

<listitem>
<para><anchor xml:id="dbdoclet.50569387_42471"
<para><anchor xml:id="dbdoclet.50569387_42471"
xreflabel="Multi-Root I/O Virtualization and Sharing specification"/>
<citetitle>Multi-Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the
most current version of this document.</para>
</listitem>

</orderedlist>

</appendix>

221
LoPAR/app_eeh_handling.xml → Platform/app_eeh_handling.xml
Unescape Escape View File

@ -1,133 +1,116 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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

<title>EEH Error Processing</title>

<para>This appendix describes the architectural intent for EEH error processing.
This appendix does not attempt to illustrate all possible scenarios, and other
<para>This appendix describes the architectural intent for EEH error processing.
This appendix does not attempt to illustrate all possible scenarios, and other
implementations are possible.</para>

<section xml:id="dbdoclet.50569381_11923">
<title>General Scenarios</title>
<para>In general, the device driver recovery consists of issuing an
<emphasis>ibm,read-slot-reset-state2</emphasis> call prior to doing any recovery
to determine if (1) the IOA is in the MMIO Stopped and DMA Stopped state (that is,
that an error has occurred which has put it into this state), and (2) whether or
not the PE has been reset by the platform in the process of entering the MMIO
<para>In general, the device driver recovery consists of issuing an
<emphasis>ibm,read-slot-reset-state2</emphasis> call prior to doing any recovery
to determine if (1) the IOA is in the MMIO Stopped and DMA Stopped state (that is,
that an error has occurred which has put it into this state), and (2) whether or
not the PE has been reset by the platform in the process of entering the MMIO
Stopped and DMA Stopped state, and then doing one of the following:</para>

<orderedlist>
<orderedlist>
<listitem>
<para>Simplest approach: </para>
<itemizedlist>
<itemizedlist>
<listitem>
<para>Reset the PE</para>
</listitem>

<listitem>
<para>Reconfigure the PE</para>
</listitem>
</itemizedlist>
</itemizedlist>
</listitem>

<listitem xml:id="dbdoclet.50569381_39262">
<para>Most general approach (detailed more in <xref linkend="dbdoclet.50569381_38095"/>): </para>
<itemizedlist>
<itemizedlist>
<listitem>
<para>Release the PE for <emphasis>Load</emphasis> /<emphasis>Store</emphasis></para>
</listitem>

<listitem>
<para>Issue <emphasis>Load</emphasis> /<emphasis> Store</emphasis> instructions t
o get any desired state information from the IOA</para>
</listitem>

<listitem>
<para>Call the <emphasis>ibm,slot-error-detail</emphasis> RTAS call to get the
<para>Call the <emphasis>ibm,slot-error-detail</emphasis> RTAS call to get the
platform error information</para>
</listitem>

<listitem>
<para>Log the error information</para>
</listitem>

<listitem>
<para>Reset the PE</para>
</listitem>

<listitem>
<para>Reconfigure the PE</para>
</listitem>
</itemizedlist>
</itemizedlist>
</listitem>

<listitem>
<para>Most robust (no reset unless necessary): </para>
<itemizedlist>
<itemizedlist>
<listitem>
<para>Release the PE for <emphasis>Load</emphasis> /<emphasis>Store</emphasis></para>
</listitem>

<listitem>
<para>Issue <emphasis> Load</emphasis> /<emphasis> Store</emphasis> instructions
<para>Issue <emphasis> Load</emphasis> /<emphasis> Store</emphasis> instructions
to get any desired state information from the IOA</para>
</listitem>

<listitem>
<para>Call the <emphasis> ibm,slot-error-detail</emphasis> RTAS call to get the
<para>Call the <emphasis> ibm,slot-error-detail</emphasis> RTAS call to get the
platform error information</para>
</listitem>

<listitem>
<para>Log the error information</para>
</listitem>

<listitem>
<para>Device driver does IOA cleanup</para>
</listitem>

<listitem>
<para>Release the PE for DMA and restart operations (no reset) </para>
</listitem>
</itemizedlist>
</itemizedlist>
</listitem>
</orderedlist>
</orderedlist>

<para>In any scenario, after several retries of a recoverable operation, the OS
may determine that further recovery efforts should cease. In such a case,
calling <emphasis>ibm,slot-error-detail</emphasis> with <emphasis>Function</emphasis> 2
(Permanent Error), in addition to returning error information, marks that the PE is
<para>In any scenario, after several retries of a recoverable operation, the OS
may determine that further recovery efforts should cease. In such a case,
calling <emphasis>ibm,slot-error-detail</emphasis> with <emphasis>Function</emphasis> 2
(Permanent Error), in addition to returning error information, marks that the PE is
no longer accessible due to previous errors.</para>
</section>

<section xml:id="dbdoclet.50569381_38095">
<title>More Detail on the Most General Approach</title>
<para>The following gives a more detailed look at scenario #<xref linkend="dbdoclet.50569381_39262"/>
in <xref linkend="dbdoclet.50569381_11923"/>. This will be broken up into two groups of operations:
<para>The following gives a more detailed look at scenario #<xref linkend="dbdoclet.50569381_39262"/>
in <xref linkend="dbdoclet.50569381_11923"/>. This will be broken up into two groups of operations:
error logging and error recovery.</para>
<para>These scenarios assume that:</para>

<orderedlist>
<orderedlist>
<listitem>
<para>The <emphasis> ibm,configure-pe</emphasis> RTAS call is implemented.</para>
</listitem>
@ -135,18 +118,18 @@
<listitem>
<para>The attempts at recovery stop when Max_Retries_Exceeded is true.</para>
</listitem>
</orderedlist>
</orderedlist>

<section>
<title>Error Logging</title>

<orderedlist>
<orderedlist>
<listitem>
<para>If the device driver is going to capture internal IOA-specific information
as a part of the error logging process or if the IOA controlled by the device driver
requires a longer wait after reset than the normal PCI specified minimum wait time,
then the device driver determines whether its IOA has been reset as a result of entering
EEH Stopped State, by looking at the <emphasis>PE Recovery Info</emphasis> output of
<para>If the device driver is going to capture internal IOA-specific information
as a part of the error logging process or if the IOA controlled by the device driver
requires a longer wait after reset than the normal PCI specified minimum wait time,
then the device driver determines whether its IOA has been reset as a result of entering
EEH Stopped State, by looking at the <emphasis>PE Recovery Info</emphasis> output of
the <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call.</para>
</listitem>

@ -155,106 +138,106 @@
</listitem>

<listitem>
<para>If the IOA requires longer wait after reset times than the specified minimum,
and the PE was reset (see step #1) as a result of the EEH event, then wait the
<para>If the IOA requires longer wait after reset times than the specified minimum,
and the PE was reset (see step #1) as a result of the EEH event, then wait the
additional necessary time before continuing.</para>
</listitem>

<listitem xml:id="dbdoclet.50569381_59303">
<para>The OS or device driver
enables PE MMIOs by calling the <emphasis>ibm,set-eeh-option</emphasis> RTAS call
<para>The OS or device driver
enables PE MMIOs by calling the <emphasis>ibm,set-eeh-option</emphasis> RTAS call
with <emphasis>Function</emphasis> 2. </para>
</listitem>

<listitem>
<para>The OS or device driver calls the <emphasis>ibm,configure-pe</emphasis> RTAS call. </para>
<orderedlist numeration="loweralpha">
<orderedlist numeration="loweralpha">
<listitem>
<para>If the PCI fabric does not need configuring (the PE was not reset previous to the
call or was reset but was previously configured with <emphasis>ibm,configure-pe</emphasis> ),
then the call returns without doing anything, otherwise it attempts to configure
<para>If the PCI fabric does not need configuring (the PE was not reset previous to the
call or was reset but was previously configured with <emphasis>ibm,configure-pe</emphasis> ),
then the call returns without doing anything, otherwise it attempts to configure
the fabric up to but not including the endpoint IOA configuration registers.</para>
</listitem>

<listitem>
<para>If an EEH event occurs as a result of probing during the
<emphasis>ibm,configure-pe</emphasis> RTAS call that results in a
reset of the PE, the PE will be returned in the PE state of 2. Software
does not necessarily need to check this on return from the call. The case
where this occurs is expected to be rare, and probably signals a non-transient error.
In this case the software can continue on with the recovery phase of the EEH processing,
<para>If an EEH event occurs as a result of probing during the
<emphasis>ibm,configure-pe</emphasis> RTAS call that results in a
reset of the PE, the PE will be returned in the PE state of 2. Software
does not necessarily need to check this on return from the call. The case
where this occurs is expected to be rare, and probably signals a non-transient error.
In this case the software can continue on with the recovery phase of the EEH processing,
and will eventually hit the same EEH event on further processing.</para>
</listitem>
</orderedlist>
</orderedlist>
</listitem>

<listitem xml:id="dbdoclet.50569381_74560">
<para>If the PE was
reset (see step #1) as a result of the EEH event, then if the device driver is
going to gather IOA-specific information for logging, it needs to finish the
configuration of the IOA PCI configuration registers, by restoring the PCI
configuration space registers of the IOA(s) in the PE (for example, BARs,
<para>If the PE was
reset (see step #1) as a result of the EEH event, then if the device driver is
going to gather IOA-specific information for logging, it needs to finish the
configuration of the IOA PCI configuration registers, by restoring the PCI
configuration space registers of the IOA(s) in the PE (for example, BARs,
Memory Space Enable, etc.). </para>
</listitem>

<listitem xml:id="dbdoclet.50569381_29191">
<para>If desired, the
<para>If desired, the
device driver gathers IOA-specific information via MMIOs, by doing MMIOs to its IOA.</para>
</listitem>

<listitem>
<para>The OS or device driver calls <emphasis>ibm,slot-error-detail</emphasis> .
Any data captured in step #<xref linkend="dbdoclet.50569381_29191"/> is passed in the
call. Note that maximum amount of data will be captured in some cases only when the
<emphasis>ibm,slot-error-detail</emphasis> call is made with PE not in the MMIO Stopped
<para>The OS or device driver calls <emphasis>ibm,slot-error-detail</emphasis> .
Any data captured in step #<xref linkend="dbdoclet.50569381_29191"/> is passed in the
call. Note that maximum amount of data will be captured in some cases only when the
<emphasis>ibm,slot-error-detail</emphasis> call is made with PE not in the MMIO Stopped
State (as it should be in step #<xref linkend="dbdoclet.50569381_59303"/>). </para>
<orderedlist numeration="loweralpha">
<orderedlist numeration="loweralpha">
<listitem>
<para>If Max_Retries_Exceeded is true, then call <emphasis>ibm,slot-error-detail</emphasis>
<para>If Max_Retries_Exceeded is true, then call <emphasis>ibm,slot-error-detail</emphasis>
with <emphasis> Function</emphasis> 2 (Permanent Error).</para>
</listitem>

<listitem>
<para>If Max_Retries_Exceeded is not true, then call <emphasis>ibm,slot-error-detail</emphasis>
<para>If Max_Retries_Exceeded is not true, then call <emphasis>ibm,slot-error-detail</emphasis>
with <emphasis>Function</emphasis> 1(Temporary Error).</para>
</listitem>
</orderedlist>
</orderedlist>
</listitem>

<listitem>
<para>The <emphasis>ibm,slot-error-detail</emphasis> RTAS call captures whatever
PCI config space registers it can between the configuration address passed in the call
and the system (PHB), and including at the configuration address and at the PHB, and
returns them along with the device specific data in an error log in the return information
from the call. This call may encounter another EEH event, in which case it returns what
<para>The <emphasis>ibm,slot-error-detail</emphasis> RTAS call captures whatever
PCI config space registers it can between the configuration address passed in the call
and the system (PHB), and including at the configuration address and at the PHB, and
returns them along with the device specific data in an error log in the return information
from the call. This call may encounter another EEH event, in which case it returns what
information it can in the call, with a <emphasis>Status</emphasis> of 0 (Success).</para>
</listitem>

<listitem>
<para>The OS or device driver logs the log entry returned from the
<para>The OS or device driver logs the log entry returned from the
<emphasis>ibm,slot-error-detail</emphasis> RTAS call.</para>
</listitem>

<listitem>
<para>If Max_Retries_Exceeded is not true, then the next step is PE Recovery,
<para>If Max_Retries_Exceeded is not true, then the next step is PE Recovery,
otherwise stop and mark the IOA(s) in the PE as unusable.</para>
</listitem>
</orderedlist>
</orderedlist>
</section>

<section>
<title>PE Recovery</title>

<orderedlist>
<orderedlist>
<listitem>
<para>OS or device driver does a PE reset sequence. Note that this step is
required even if the PE was reset as a result of the initial EEH event, because
the error logging steps (for example, the <emphasis>ibm,configure-pe</emphasis>
or <emphasis> ibm,slot-error-detail</emphasis> calls) could have encountered
<para>OS or device driver does a PE reset sequence. Note that this step is
required even if the PE was reset as a result of the initial EEH event, because
the error logging steps (for example, the <emphasis>ibm,configure-pe</emphasis>
or <emphasis> ibm,slot-error-detail</emphasis> calls) could have encountered
another EEH event. </para>
<orderedlist numeration="loweralpha">
<orderedlist numeration="loweralpha">
<listitem>
<para>The device driver or OS calls <emphasis>ibm,set-slot-reset</emphasis> with
<para>The device driver or OS calls <emphasis>ibm,set-slot-reset</emphasis> with
<emphasis>Function</emphasis> 1 or 3 to activate the reset.</para>
</listitem>

@ -263,26 +246,26 @@
</listitem>

<listitem>
<para>The device driver or OS calls <emphasis>ibm,set-slot-reset</emphasis> with
<para>The device driver or OS calls <emphasis>ibm,set-slot-reset</emphasis> with
<emphasis>Function</emphasis> 0 to deactivate the reset.</para>
</listitem>

<listitem>
<para>The minimum reset inactive to first configuration cycles is waited.
If the IOA requires more than the standard PCI specified time, then wait that
<para>The minimum reset inactive to first configuration cycles is waited.
If the IOA requires more than the standard PCI specified time, then wait that
longer time, instead.</para>
</listitem>
</orderedlist>
</orderedlist>
</listitem>

<listitem>
<para>The OS or device driver calls <emphasis>ibm,configure-pe.</emphasis>
<note><para>If an EEH event occurs as a result of probing
during the <emphasis>ibm,configure-pe</emphasis> RTAS call that results in a reset
of the PE, the PE will be returned in the PE state of 2. Software does not necessarily
need to check this on return from the call. The case where this occurs is expected to
be rare, and probably signals a non-transient error. In this case the software can
continue on with the recovery phase of the EEH processing, and will eventually hit
<note><para>If an EEH event occurs as a result of probing
during the <emphasis>ibm,configure-pe</emphasis> RTAS call that results in a reset
of the PE, the PE will be returned in the PE state of 2. Software does not necessarily
need to check this on return from the call. The case where this occurs is expected to
be rare, and probably signals a non-transient error. In this case the software can
continue on with the recovery phase of the EEH processing, and will eventually hit
the same EEH event on further processing.</para></note>
</para>
</listitem>
@ -294,7 +277,7 @@
<listitem>
<para>The device driver initializes the IOA for operations.</para>
</listitem>
</orderedlist>
</orderedlist>

</section>
</section>

1289
Platform/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

99
LoPAR/bk_main.xml → Platform/bk_main.xml
Unescape Escape View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
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.
@ -19,12 +19,13 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
status="draft"
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>
<title>Platform</title>
<subtitle>Linux on Power Architecture Reference</subtitle>

<info>
<author>
@ -41,7 +42,7 @@
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.9</releaseinfo>
<releaseinfo>Revision 0.5_pre5</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

@ -56,71 +57,25 @@
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.
architectural details for the base Platform hardware associated with an OpenPOWER Systems.
The base content for this document were contributed to the OpenPOWER Foundation in the
<link xlink:href="https://openpowerfoundation.org/?resource_lib=linux-on-power-architecture-platform-reference"><citetitle>IBM
Linux on Power Architecture Platform Reference (LoPAPR) Draft</citetitle></link>
<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 as a Workgroup Note. It should
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 Non-standard Track, Workgroup Note work product owned by the
<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 but meets
the requirements of the 1.10 level. Comments,
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>
<link xlink:href="http://tbd.openpowerfoundation.org">TBD</link>.</para>
</abstract>

<revhistory>
<!-- TODO: Update as new revisions created -->
<revision>
<date>2020-08-12</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.9:
<itemizedlist spacing="compact">
<listitem><para>First published Workgroup Note</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2020-06-11</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.9_pre7:
<itemizedlist spacing="compact">
<listitem><para>First public review, remove Confidential markings</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2020-04-20</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.9_pre6:
<itemizedlist spacing="compact">
<listitem><para>Re-merge 5 sub-docs back into one matching PAPR.</para></listitem>
<listitem><para>Set Revision to match PAPR spec level (2.9).</para></listitem>
<listitem><para>Miscellaneous formatting improvements. No technical updates.</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2020-04-06</date>
<revdescription>
@ -374,49 +329,29 @@

<!-- 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"/>
<xi:include href="../common/ch_LoPAR_preface.xml"/>

<!-- Chapter heading files -->
<xi:include href="ch_introduction.xml"/>
<xi:include href="ch_platform_intro.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"/>
<xi:include href="ch_io_topology.xml"/>
<xi:include href="ch_io_devices.xml"/>
<xi:include href="ch_product_topology.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"/>
<xi:include href="../common/app_EOD.xml"/>

</book>

849
LoPAR/ch_address_map.xml → Platform/ch_address_map.xml
View File

File diff suppressed because it is too large Load Diff

614
LoPAR/ch_interrupt_controller.xml → Platform/ch_interrupt_controller.xml
Unescape Escape View File

@ -1,301 +1,285 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569331_37856"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569331_37856"
version="5.0"
xml:lang="en">
<title>Interrupt Controller</title>

<para>This chapter specifies the requirements for the LoPAR interrupt
controller. Platforms may chose to virtualize the interrupt controller or to
<para>This chapter specifies the requirements for the LoPAR interrupt
controller. Platforms may chose to virtualize the interrupt controller or to
provide the PowerPC External Interrupt option. </para>

<section>
<title>Interrupt Controller Virtualization</title>
<para>Virtualization of the interrupt controller is done through the
Interrupt Support hcalls. See <xref linkend="dbdoclet.50569344_26787"/>.</para>
<para>Virtualization of the interrupt controller is done through the
Interrupt Support hcalls. See <xref linkend="LoPAR.Virtualization"/>.</para>
</section>

<section xml:id="dbdoclet.50569331_29157">
<title>PowerPC External Interrupt Option</title>
<para>The PowerPC External Interrupt option is based upon a subset of the
PowerPC External Interrupt Architecture. The PowerPC External Interrupt
Architecture contains a register-level architectural definition of an interrupt
control structure. This architecture defines means for assigning properties
such as priority, destination, etc., to I/O and interprocessor interrupts, as
well as an interface for presenting them to processors. It supports both
specific and distributed methods for interrupt delivery. See also
<!-- FIXME: xref linkend="error_section"/--><citetitle>A PowerPC External
<para>The PowerPC External Interrupt option is based upon a subset of the
PowerPC External Interrupt Architecture. The PowerPC External Interrupt
Architecture contains a register-level architectural definition of an interrupt
control structure. This architecture defines means for assigning properties
such as priority, destination, etc., to I/O and interprocessor interrupts, as
well as an interface for presenting them to processors. It supports both
specific and distributed methods for interrupt delivery. See also
<!-- FIXME: xref linkend="error_section"/--><citetitle>A PowerPC External
Interrupt</citetitle>.htm#38341.--&gt;</para>
<para>In NUMA platform configurations, the interrupt controllers may be
configured in disjoint domains. The firmware makes the server numbers visible
to any single OS image appear to come from a single space without duplication.
This may be done by appropriately initializing the interrupt presentation
controllers or the firmware may translate the server numbers presented to it in
RTAS calls before entering them into the interrupt controller registers. The OS
is made aware that certain interrupts are only served by certain servers by the
inclusion of the <emphasis role="bold"><literal>&#x201C;ibm,interrupt-domain&#x201D;</literal></emphasis>
<para>In NUMA platform configurations, the interrupt controllers may be
configured in disjoint domains. The firmware makes the server numbers visible
to any single OS image appear to come from a single space without duplication.
This may be done by appropriately initializing the interrupt presentation
controllers or the firmware may translate the server numbers presented to it in
RTAS calls before entering them into the interrupt controller registers. The OS
is made aware that certain interrupts are only served by certain servers by the
inclusion of the <emphasis role="bold"><literal>&#x201C;ibm,interrupt-domain&#x201D;</literal></emphasis>
property in the interrupt controller nodes.</para>

<section xml:id="sec_ext_int_opt_req">
<title>PowerPC External Interrupt Option Requirements</title>
<para>The following are the requirements for the PowerPC External
Interrupt option. Additional requirements and information relative to the MSI
option, when implemented with this option, are listed in <xref
<para>The following are the requirements for the PowerPC External
Interrupt option. Additional requirements and information relative to the MSI
option, when implemented with this option, are listed in <xref
linkend="dbdoclet.50569331_33067"/>.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms must implement interrupt architectures
that are in register-level architectural compliance with
<!-- FIXME: <xref linkend="error_section"/ --><citetitle>A PowerPC External
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms must implement interrupt architectures
that are in register-level architectural compliance with
<!-- FIXME: <xref linkend="error_section"/ --><citetitle>A PowerPC External
Interrupt</citetitle>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
one or more PowerPC External Interrupt Presentation node(s), as children of the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
one or more PowerPC External Interrupt Presentation node(s), as children of the
root node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
an <emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-server#s&#x201D;</literal></emphasis> and an
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis> property as defined for
each processor in the processor&#x2019;s <emphasis role="bold"><literal>/cpus/cpu</literal></emphasis>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
an <emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-server#s&#x201D;</literal></emphasis> and an
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis> property as defined for
each processor in the processor&#x2019;s <emphasis role="bold"><literal>/cpus/cpu</literal></emphasis>
node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The various
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-server#s&#x201D;</literal></emphasis> property values seen by a
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The various
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-server#s&#x201D;</literal></emphasis> property values seen by a
single OS image must be all unique.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> If an OS image sees multiple global interrupt
server queues, the <emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> If an OS image sees multiple global interrupt
server queues, the <emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis>
properties associated with the various queues must have unique values. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
a PowerPC External Interrupt Source Controller node, as defined for each Bus
Unit Controller (BUC) that can generate PowerPC External Interrupt Architecture
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must include
a PowerPC External Interrupt Source Controller node, as defined for each Bus
Unit Controller (BUC) that can generate PowerPC External Interrupt Architecture
interrupts, as a child of the platform&#x2019;s root node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must conform
to the <emphasis><xref linkend="dbdoclet.50569387_40740"/></emphasis> and
include the appropriate mapping and interrupt properties to allow the mapping
of all non-zero XISR values (<emphasis>interrupt#</emphasis>) to the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform&#x2019;s OF device tree must conform
to the <emphasis><xref linkend="dbdoclet.50569387_40740"/></emphasis> and
include the appropriate mapping and interrupt properties to allow the mapping
of all non-zero XISR values (<emphasis>interrupt#</emphasis>) to the
corresponding node generating the interrupt. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The PowerPC External Interrupt Presentation
Controller node must not contain the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The PowerPC External Interrupt Presentation
Controller node must not contain the
<emphasis role="bold"><literal>&#x201C;used-by-rtas&#x201D;</literal></emphasis> property. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The PowerPC External Interrupt Source Controller
node must contain the <emphasis role="bold"><literal>&#x201C;used-by-rtas&#x201D;</literal></emphasis>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The PowerPC External Interrupt Source Controller
node must contain the <emphasis role="bold"><literal>&#x201C;used-by-rtas&#x201D;</literal></emphasis>
property.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> If the interrupt hardware is configured such that,
viewed from any given OS image, any interrupt source controller cannot direct
interrupts to any interrupt presentation controller, then the platform must
include the <emphasis role="bold"><literal>&#x201C;ibm,interrupt-domain&#x201D;</literal></emphasis> property
in all interrupt source and presentation controller nodes for that OS so that
the OS can determine the servers that may be valid targets for any given
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> If the interrupt hardware is configured such that,
viewed from any given OS image, any interrupt source controller cannot direct
interrupts to any interrupt presentation controller, then the platform must
include the <emphasis role="bold"><literal>&#x201C;ibm,interrupt-domain&#x201D;</literal></emphasis> property
in all interrupt source and presentation controller nodes for that OS so that
the OS can determine the servers that may be valid targets for any given
interrupt.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> All interrupt controller registers must be
accessed via Caching-Inhibited, Memory Coherence not required and Guarded
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> All interrupt controller registers must be
accessed via Caching-Inhibited, Memory Coherence not required and Guarded
Storage mapping.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must manage the Available Processor
Mask Register so that global interrupts (server number field of the eXternal
Interrupt Vector Entry (XIVE) set to a value from
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis>) are only sent to one
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must manage the Available Processor
Mask Register so that global interrupts (server number field of the eXternal
Interrupt Vector Entry (XIVE) set to a value from
<emphasis role="bold"><literal>&#x201C;ibm,ppc-interrupt-gserver#s&#x201D;</literal></emphasis>) are only sent to one
of the active processors.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must initialize the interrupt
priority in each XIVE to the least favored level (0xFF), enable any associated
IER bit for interrupt sources owned by the OS, and set the Current Processor
Priority Register to the Most favored level (0x00) prior to the transfer of
control to the OS so that no interrupts are signaled to a processor until the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must initialize the interrupt
priority in each XIVE to the least favored level (0xFF), enable any associated
IER bit for interrupt sources owned by the OS, and set the Current Processor
Priority Register to the Most favored level (0x00) prior to the transfer of
control to the OS so that no interrupts are signaled to a processor until the
OS has taken explicit action.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Any implemented PowerPC External Interrupt
Architecture registers that are not reported in specific interrupt source or
destination controller nodes (such as the APM register) must be included in the
<emphasis role="bold"><literal>&#x201C;reg&#x201D;</literal></emphasis> property of the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Any implemented PowerPC External Interrupt
Architecture registers that are not reported in specific interrupt source or
destination controller nodes (such as the APM register) must be included in the
<emphasis role="bold"><literal>&#x201C;reg&#x201D;</literal></emphasis> property of the
<emphasis>/reserved</emphasis> node.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569331_84135">
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The interrupt source controller must prevent signalling new
interrupts when the XIVE interrupt priority field is set to the least favored
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The interrupt source controller must prevent signalling new
interrupts when the XIVE interrupt priority field is set to the least favored
level.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Interrupt controllers that do not implement the
behavior of Requirement <xref linkend="dbdoclet.50569331_84135"/>, must provide
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Interrupt controllers that do not implement the
behavior of Requirement <xref linkend="dbdoclet.50569331_84135"/>, must provide
an Interrupt Enable Register (IER) which can be manipulated by RTAS, </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must assign the Bus Unit Identifiers
(BUIDs) such that they form a compact address space. That is, while the first
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> The platform must assign the Bus Unit Identifiers
(BUIDs) such that they form a compact address space. That is, while the first
BUID value is arbitrary, subsequent BUIDs should be contiguous.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms implementing interrupt server number
fields greater than 8 bits must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-server#-size&#x201D;</literal></emphasis> property in the interrupt
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms implementing interrupt server number
fields greater than 8 bits must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-server#-size&#x201D;</literal></emphasis> property in the interrupt
source controller node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms implementing interrupt buid number
fields greater than 9 bits must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-buid-size&#x201D;</literal></emphasis> property in the interrupt
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms implementing interrupt buid number
fields greater than 9 bits must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-buid-size&#x201D;</literal></emphasis> property in the interrupt
presentation controller node.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
<term><emphasis role="bold">R1-<xref linkend="sec_ext_int_opt_req"
xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-server-ranges&#x201D;</literal></emphasis> property in the
<para><emphasis role="bold">For the PowerPC External
Interrupt option:</emphasis> Platforms must include the
<emphasis role="bold"><literal>&#x201C;ibm,interrupt-server-ranges&#x201D;</literal></emphasis> property in the
interrupt presentation controller node.</para>
</listitem>
</varlistentry>
@ -305,42 +289,42 @@

<section>
<title>PowerPC External Interrupt Option Properties</title>
<para>See <xref linkend="dbdoclet.50569368_91814"/> for property definitions.</para>
<para>See <xref linkend="LoPAR.DeviceTree"/> for property definitions.</para>
</section>

<section xml:id="dbdoclet.50569331_33067">
<title>MSI Option</title>
<para>The Message Signaled Interrupt (MSI) or Enhanced MSI (MSI-X)
capability of PCI IOAs in many cases allows for greater flexibility in
assignment of external interrupts to IOA functions than the predecessor Level
Sensitive Interrupt (LSI) capability, and in some cases treats MSIs as a
resource pool that can be reassigned based on availability of MSIs and the need
of an IOA function for more interrupts than initially assigned. Platforms that
implement the MSI option implement the <emphasis>ibm,change-msi</emphasis> and
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls. These RTAS
calls manage interrupts in a platform that implements the MSI option. In
particular, these calls assign additional MSI resources to an IOA function (as
defined by its PCI configuration address: <emphasis>PHB_Unit_ID_Hi,
PHB_Unit_ID_Low, and config_addr</emphasis>), when supported by the platform.
See <xref linkend="dbdoclet.50569332_61719"/> for more information on theses RTAS calls for
<para>The Message Signaled Interrupt (MSI) or Enhanced MSI (MSI-X)
capability of PCI IOAs in many cases allows for greater flexibility in
assignment of external interrupts to IOA functions than the predecessor Level
Sensitive Interrupt (LSI) capability, and in some cases treats MSIs as a
resource pool that can be reassigned based on availability of MSIs and the need
of an IOA function for more interrupts than initially assigned. Platforms that
implement the MSI option implement the <emphasis>ibm,change-msi</emphasis> and
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls. These RTAS
calls manage interrupts in a platform that implements the MSI option. In
particular, these calls assign additional MSI resources to an IOA function (as
defined by its PCI configuration address: <emphasis>PHB_Unit_ID_Hi,
PHB_Unit_ID_Low, and config_addr</emphasis>), when supported by the platform.
See <xref linkend="LoPAR.RTAS"/> for more information on theses RTAS calls for
MSI management.</para>
<para>This architecture will refer generically to the MSI and MSI-X
capabilities as simply &#x201C;MSI,&#x201D; except where differentiation is
required. In this architecture, MSIs and LSIs are what the IOA function
signals, and what the software sees for that signal is ultimately the LSI or
MSI <emphasis>source number</emphasis>. The interrupt source numbers returned
by the <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call are
<para>This architecture will refer generically to the MSI and MSI-X
capabilities as simply &#x201C;MSI,&#x201D; except where differentiation is
required. In this architecture, MSIs and LSIs are what the IOA function
signals, and what the software sees for that signal is ultimately the LSI or
MSI <emphasis>source number</emphasis>. The interrupt source numbers returned
by the <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call are
the numbers used to control the interrupt as in the <emphasis>ibm,get-xive</emphasis>,
<emphasis>ibm,set-xive</emphasis>, <emphasis>ibm,int-on</emphasis>,
<emphasis>ibm,set-xive</emphasis>, <emphasis>ibm,int-on</emphasis>,
and <emphasis>ibm,int-off</emphasis> RTAS calls.</para>
<para>PCI-X and PCI Express IOA functions that signal interrupts are
required by the PCI specifications to implement either the MSI or MSI-X
interrupt capabilities, or both. For PCI Express, it is expected that IOAs will
only support MSI or MSI-X (that is, no support for LSIs). When both MSI and
MSI-X are implemented by an IOA function, the MSI method will be configured by
the platform, but may be overridden by the OS or device driver, via the
<emphasis>ibm,change-msi</emphasis> RTAS call, to be MSI-X or, if assigned by
the firmware, to LSI (by removal of the MSIs assigned).
<para>PCI-X and PCI Express IOA functions that signal interrupts are
required by the PCI specifications to implement either the MSI or MSI-X
interrupt capabilities, or both. For PCI Express, it is expected that IOAs will
only support MSI or MSI-X (that is, no support for LSIs). When both MSI and
MSI-X are implemented by an IOA function, the MSI method will be configured by
the platform, but may be overridden by the OS or device driver, via the
<emphasis>ibm,change-msi</emphasis> RTAS call, to be MSI-X or, if assigned by
the firmware, to LSI (by removal of the MSIs assigned).
<xref linkend="dbdoclet.50569331_99447"/> summarizes the LSI and MSI support.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569331_99447">
@ -382,9 +366,9 @@
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">Initial interrupt assignment<footnote
xml:id="pgfId-1012212"><para>Assignment means to allocate the platform
resources and to enable the interrupt in the IOA function&#x2019;s
<emphasis role="bold">Initial interrupt assignment<footnote
xml:id="pgfId-1012212"><para>Assignment means to allocate the platform
resources and to enable the interrupt in the IOA function&#x2019;s
configuration space.</para></footnote></emphasis>
</para>
</entry>
@ -422,8 +406,8 @@
<para>LSI or MSI</para>
</entry>
<entry>
<para>LSI<footnote xml:id="pgfId-1001089"><para>If MSIs are to
be supported, the device driver must enable via the
<para>LSI<footnote xml:id="pgfId-1001089"><para>If MSIs are to
be supported, the device driver must enable via the
<emphasis>ibm,change-msi</emphasis> RTAS call.</para></footnote></para>
</entry>
</row>
@ -432,7 +416,7 @@
<para>PCI-X</para>
</entry>
<entry>
<para>Encouraged when interrupts are required, for backward
<para>Encouraged when interrupts are required, for backward
platform compatibility</para>
</entry>
<entry>
@ -448,8 +432,8 @@
<para>LSI or MSI</para>
</entry>
<entry>
<para>LSI<footnote xml:id="pgfId-1001101"><para>If MSIs are to
be supported, the device driver must enable via the
<para>LSI<footnote xml:id="pgfId-1001101"><para>If MSIs are to
be supported, the device driver must enable via the
<emphasis>ibm,change-msi</emphasis> RTAS call.</para></footnote></para>
</entry>
</row>
@ -474,11 +458,11 @@
<para>MSI</para>
</entry>
<entry>
<para>MSI<footnote xml:id="pgfId-1012199"><para>MSI as an
initial assignment means that one or more MSIs are reported as being available
for the IOA function. In addition, LSIs may also be reported but not enabled,
in which case if the device driver removes the assigned MSIs, the assigned LSI
are enabled by the platform firmware in the IOA function&#x2019;s configuration
<para>MSI<footnote xml:id="pgfId-1012199"><para>MSI as an
initial assignment means that one or more MSIs are reported as being available
for the IOA function. In addition, LSIs may also be reported but not enabled,
in which case if the device driver removes the assigned MSIs, the assigned LSI
are enabled by the platform firmware in the IOA function&#x2019;s configuration
space.</para></footnote></para>
</entry>
</row>
@ -489,24 +473,24 @@
</entry>
<entry>
<para>LSI or not supported<footnote xml:id="pgfId-1001611">
<para>If PCI Express IOA function does not support LSI,
<para>If PCI Express IOA function does not support LSI,
then this combination is not supported.</para></footnote></para>
</entry>
<entry>
<para>LSI<footnote xml:id="pgfId-1001616">
<para>If PCI Express
IOA function does not support LSI, then this combination is not
<para>If PCI Express
IOA function does not support LSI, then this combination is not
supported.</para></footnote> or MSI</para>
</entry>
<entry>
<para>LSI<footnote xml:id="pgfId-1001598">
<para>If the PCI
Express IOA function does not support LSI, then the platform will set the
initial interrupt assignment to MSI, and if the device driver does not support
MSI, then the IOA function will not be configurable (that is, conversion from
MSI to LSI through the bridge is not supported by this architecture). If LSI is
the initial assignment, then if MSIs are to be supported, device driver must
enable via the <emphasis>ibm,change-msi</emphasis> RTAS
<para>If the PCI
Express IOA function does not support LSI, then the platform will set the
initial interrupt assignment to MSI, and if the device driver does not support
MSI, then the IOA function will not be configurable (that is, conversion from
MSI to LSI through the bridge is not supported by this architecture). If LSI is
the initial assignment, then if MSIs are to be supported, device driver must
enable via the <emphasis>ibm,change-msi</emphasis> RTAS
call.</para></footnote></para>
</entry>
</row>
@ -514,191 +498,191 @@
</tgroup>
</table>

<para>The <emphasis>ibm,change-msi</emphasis> RTAS call is used to query
the initial number of MSIs assigned to a PCI configuration address and to
request a change in the number of MSIs assigned. The MSIs interrupt source
numbers assigned to an IOA function are returned via the
<emphasis>ibm,query-interrupt-source-number</emphasis>
RTAS call. In addition, when the
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is
implemented, it may be used to query the LSI source numbers, also. The
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is called
iteratively, once for each interrupt assigned to the IOA function. When an IOA
function receives an initial assignment of an LSI, the interrupt number for
that LSI may also be obtained through the same OF device tree properties that
are used to report interrupt information when the
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is not
<para>The <emphasis>ibm,change-msi</emphasis> RTAS call is used to query
the initial number of MSIs assigned to a PCI configuration address and to
request a change in the number of MSIs assigned. The MSIs interrupt source
numbers assigned to an IOA function are returned via the
<emphasis>ibm,query-interrupt-source-number</emphasis>
RTAS call. In addition, when the
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is
implemented, it may be used to query the LSI source numbers, also. The
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is called
iteratively, once for each interrupt assigned to the IOA function. When an IOA
function receives an initial assignment of an LSI, the interrupt number for
that LSI may also be obtained through the same OF device tree properties that
are used to report interrupt information when the
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call is not
implemented.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The platform must implement the MSI
<para>The platform must implement the MSI
option if the platform contains at least one PCI Express HB.</para>
<para><emphasis role="bold">Architecture and Software Note:</emphasis> The MSI
option may also be implemented in the absence of any PCI Express HBs. In that
case, the implementation of the MSI option is via the presence of the
implementation of the associated <emphasis>ibm,change-msi</emphasis> and
<para><emphasis role="bold">Architecture and Software Note:</emphasis> The MSI
option may also be implemented in the absence of any PCI Express HBs. In that
case, the implementation of the MSI option is via the presence of the
implementation of the associated <emphasis>ibm,change-msi</emphasis> and
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must implement the PowerPC External Interrupt option.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must implement the <emphasis>ibm,change-msi</emphasis>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must implement the <emphasis>ibm,change-msi</emphasis>
and <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must initially assign LSI or MSIs to IOA functions as
defined in <xref linkend="dbdoclet.50569331_99447"/> and must enable the
assigned interrupts in the IOA function&#x2019;s configuration space (the
interrupts remains disabled at the PHB, and must be enabled by the device
driver though the <emphasis>ibm,set-xive</emphasis> and
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must initially assign LSI or MSIs to IOA functions as
defined in <xref linkend="dbdoclet.50569331_99447"/> and must enable the
assigned interrupts in the IOA function&#x2019;s configuration space (the
interrupts remains disabled at the PHB, and must be enabled by the device
driver though the <emphasis>ibm,set-xive</emphasis> and
<emphasis>ibm,int-on</emphasis> RTAS calls.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569331_84312">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform
must provide a minimum of one MSI per IOA function (that is per each unique PCI
configuration address, including the Function #) to be supported beneath the
interrupt source controller, and any given MSI and MSI source number must not
be shared between functions or within one function (even within the same
The platform
must provide a minimum of one MSI per IOA function (that is per each unique PCI
configuration address, including the Function #) to be supported beneath the
interrupt source controller, and any given MSI and MSI source number must not
be shared between functions or within one function (even within the same
PE).</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569331_63544">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform
must provide at least one MSI port (the address written by the MSI) per
The platform
must provide at least one MSI port (the address written by the MSI) per
Partitionable Endpoint (PE).</para>
<para><emphasis role="bold">Platform Implementation Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569331_84312"/> in conjunction with Requirement <xref
linkend="dbdoclet.50569331_63544"/> may have certain ramifications on the
design. Depending on the implementation, a unique MSI port per IOA function may
<para><emphasis role="bold">Platform Implementation Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569331_84312"/> in conjunction with Requirement <xref
linkend="dbdoclet.50569331_63544"/> may have certain ramifications on the
design. Depending on the implementation, a unique MSI port per IOA function may
be required, and not just a unique port per PE.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option with the
LPAR option:</emphasis> The platform must prevent a PE from creating an
interrupt to a partition other than those to which the PE is authorized by the
<para><emphasis role="bold">For the MSI option with the
LPAR option:</emphasis> The platform must prevent a PE from creating an
interrupt to a partition other than those to which the PE is authorized by the
platform to interrupt.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must set the PCI configuration space MSI registers properly in an
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must set the PCI configuration space MSI registers properly in an
IOA at all the following times:</para>

<orderedlist numeration="loweralpha">
<orderedlist numeration="loweralpha">
<listitem>
<para>Initial boot time</para>
</listitem>

<listitem>
<para>During the <emphasis>ibm,configure-connector</emphasis> RTAS
<para>During the <emphasis>ibm,configure-connector</emphasis> RTAS
call</para>
</listitem>

<listitem>
<para>During the <emphasis>ibm,change-msi</emphasis> or
<para>During the <emphasis>ibm,change-msi</emphasis> or
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call</para>
</listitem>
</orderedlist>
</orderedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must initialize any bridges necessary to appropriately route
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must initialize any bridges necessary to appropriately route
interrupts at all the following times:</para>

<orderedlist numeration="loweralpha">
<orderedlist numeration="loweralpha">
<listitem>
<para>At initial boot time</para>
</listitem>

<listitem>
<para>During the <emphasis>ibm,configure-connector</emphasis> RTAS
<para>During the <emphasis>ibm,configure-connector</emphasis> RTAS
call</para>
</listitem>

<listitem>
<para>During the <emphasis>ibm,configure-bridge</emphasis> RTAS
<para>During the <emphasis>ibm,configure-bridge</emphasis> RTAS
call</para>
</listitem>

<listitem>
<para>During the <emphasis>ibm,change-msi</emphasis> or
<para>During the <emphasis>ibm,change-msi</emphasis> or
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call</para>
</listitem>
</orderedlist>
</orderedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must provide the <emphasis role="bold"><literal>&#x201C;ibm,req#msi&#x201D;</literal></emphasis>
property for any IOA function which is
requesting MSIs; at initial boot time and during the
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform must provide the <emphasis role="bold"><literal>&#x201C;ibm,req#msi&#x201D;</literal></emphasis>
property for any IOA function which is
requesting MSIs; at initial boot time and during the
<emphasis>ibm,configure-connector</emphasis> RTAS call.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569331_62532">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569331_33067"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the MSI option:</emphasis>
The platform
must remember and recover on error recovery any previously allocated and setup
The platform
must remember and recover on error recovery any previously allocated and setup
interrupt information in the platform-owned hardware.</para>
<para><emphasis role="bold">Software and Platform Implementation Note:</emphasis> In
Requirement <xref linkend="dbdoclet.50569331_62532"/>, it is possible that some
interrupts may be lost as part of the error recovery, and software should be
<para><emphasis role="bold">Software and Platform Implementation Note:</emphasis> In
Requirement <xref linkend="dbdoclet.50569331_62532"/>, it is possible that some
interrupts may be lost as part of the error recovery, and software should be
implemented to take into consideration that possibility.</para>
</listitem>
</varlistentry>
@ -709,30 +693,30 @@

<section xml:id="sec_plat_rsvd_int_opt">
<title>Platform Reserved Interrupt Priority Level Option</title>
<para>The Platform Reserved Interrupt Priority Level option allows
platforms to reserve interrupt priority levels for internal uses. When the
platform exercises this option, it notifies the client program via the OF
device tree <emphasis role="bold"><literal>&#x201C;ibm,plat-res-int-priorities&#x201D;</literal></emphasis>
<para>The Platform Reserved Interrupt Priority Level option allows
platforms to reserve interrupt priority levels for internal uses. When the
platform exercises this option, it notifies the client program via the OF
device tree <emphasis role="bold"><literal>&#x201C;ibm,plat-res-int-priorities&#x201D;</literal></emphasis>
property of the <emphasis role="bold"><literal>root</literal></emphasis> node of the device tree.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_plat_rsvd_int_opt"
<term><emphasis role="bold">R1-<xref linkend="sec_plat_rsvd_int_opt"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Platform Reserved
Interrupt Priority Level option: The platform must include
the</emphasis><emphasis role="bold"><literal>&#x201C;ibm,plat-res-int-priorities&#x201D;</literal></emphasis>
<para><emphasis role="bold">For the Platform Reserved
Interrupt Priority Level option: The platform must include
the</emphasis><emphasis role="bold"><literal>&#x201C;ibm,plat-res-int-priorities&#x201D;</literal></emphasis>
property in the <emphasis role="bold"><literal>root</literal></emphasis> node of the device tree.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_plat_rsvd_int_opt"
<term><emphasis role="bold">R1-<xref linkend="sec_plat_rsvd_int_opt"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Platform Reserved
Interrupt Priority Level option:</emphasis> The platform must not reserve
<para><emphasis role="bold">For the Platform Reserved
Interrupt Priority Level option:</emphasis> The platform must not reserve
priority levels 0x00 through 0x07 and 0xFF for internal use. </para>
</listitem>
</varlistentry>

646
LoPAR/ch_io_devices.xml → Platform/ch_io_devices.xml
View File

File diff suppressed because it is too large Load Diff

2005
LoPAR/ch_io_topology.xml → Platform/ch_io_topology.xml
View File

File diff suppressed because it is too large Load Diff

456
LoPAR/ch_nonvolatile_memory.xml → Platform/ch_nonvolatile_memory.xml
Unescape Escape View File

@ -1,152 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569333_15433"
version="5.0" xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569333_15433"
version="5.0" xml:lang="en">
<title>Non-Volatile Memory</title>

<para>This chapter describes the requirements relating to Non-Volatile
Memory. Non-Volatile Memory is the repository for system information that must
<para>This chapter describes the requirements relating to Non-Volatile
Memory. Non-Volatile Memory is the repository for system information that must
be persistent across reboots and power cycles. </para>

<section xml:id="sec_nvram_sys_req">
<title>System Requirements</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms must implement at least 8 KB of
Non-Volatile Memory. The actual amount is platform dependent and must allow for
4 KB for the OS. Platforms must provide an additional 4 KB for each installed
<para>Platforms must implement at least 8 KB of
Non-Volatile Memory. The actual amount is platform dependent and must allow for
4 KB for the OS. Platforms must provide an additional 4 KB for each installed
OS beyond the first.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Non-Volatile Memory must maintain its
<para>Non-Volatile Memory must maintain its
contents in the absence of system power.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Firmware must reinitialize NVRAM to a
<para>Firmware must reinitialize NVRAM to a
bootable state if NVRAM data corruption is detected.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_sys_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>OSs must reinitialize their own NVRAM
partitions if NVRAM data corruption is detected. OSs may create free space from
the first corrupted NVRAM partition header to the end of NVRAM and utilize this
<para>OSs must reinitialize their own NVRAM
partitions if NVRAM data corruption is detected. OSs may create free space from
the first corrupted NVRAM partition header to the end of NVRAM and utilize this
area to initialize their NVRAM partitions.</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Hardware Implementation Note:</emphasis> The NVRAM terminology used in this
chapter goes back to historic implementations that have used battery-powered
RAM to implement the non-volatile memory. It should be understood that this is
not the only possible implementation. Implementers need to understand that
there are no limits on the frequency of writing to the non-volatile memory, so
certain technologies may not be applicable. Also, it should be noted that the
<emphasis>nvram-fetch</emphasis> and <emphasis>nvram-store</emphasis> RTAS
calls do not allow a &#x201C;busy&#x201D; Status return, and this may further
<para><emphasis role="bold">Hardware Implementation Note:</emphasis> The NVRAM terminology used in this
chapter goes back to historic implementations that have used battery-powered
RAM to implement the non-volatile memory. It should be understood that this is
not the only possible implementation. Implementers need to understand that
there are no limits on the frequency of writing to the non-volatile memory, so
certain technologies may not be applicable. Also, it should be noted that the
<emphasis>nvram-fetch</emphasis> and <emphasis>nvram-store</emphasis> RTAS
calls do not allow a &#x201C;busy&#x201D; Status return, and this may further
limit the implementation choices.</para>
<para><emphasis role="bold">Software Implementation Note:</emphasis> Refer to <xref linkend="dbdoclet.50569332_26944"/>
<para><emphasis role="bold">Software Implementation Note:</emphasis> Refer to <xref linkend="LoPAR.RTAS"/>
for information on accessing NVRAM.</para>
</section>

<section xml:id="sec_nvram_structure">
<title>Structure</title>
<para>NVRAM is formatted as a set of NVRAM partitions that adhere to the
structure in <xref linkend="dbdoclet.50569333_37259"/>. NVRAM partitions are
prefixed with a header containing <emphasis>signature</emphasis>,
<emphasis>checksum</emphasis>, <emphasis>length</emphasis>, and
<emphasis>name</emphasis> fields. The structure of the <emphasis>data</emphasis> field
is defined by the NVRAM partition creator/owner (designated by
<para>NVRAM is formatted as a set of NVRAM partitions that adhere to the
structure in <xref linkend="dbdoclet.50569333_37259"/>. NVRAM partitions are
prefixed with a header containing <emphasis>signature</emphasis>,
<emphasis>checksum</emphasis>, <emphasis>length</emphasis>, and
<emphasis>name</emphasis> fields. The structure of the <emphasis>data</emphasis> field
is defined by the NVRAM partition creator/owner (designated by
<emphasis>signature</emphasis> and <emphasis>name</emphasis>). </para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>NVRAM partitions must be structured as shown
<para>NVRAM partitions must be structured as shown
in <xref linkend="dbdoclet.50569333_37259"/>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>All NVRAM space must be accounted for by
<para>All NVRAM space must be accounted for by
NVRAM partitions.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
<term><emphasis role="bold">R1-<xref linkend="sec_nvram_structure"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>All IBM-defined NVRAM partitions that are
intended to be IBM-unique must have names prefixed with the ASCII
<para>All IBM-defined NVRAM partitions that are
intended to be IBM-unique must have names prefixed with the ASCII
representation of the four characters: <emphasis>ibm,</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Software Implementation Note:</emphasis> Although the data
areas of NVRAM partitions are not required to have error checking, it is
strongly recommended that the system software implement robust data structures
and error checking. Loss of NVRAM structures due to data corruption can be
catastrophic, potentially leading to OS reinstallation and/or complete system
<para><emphasis role="bold">Software Implementation Note:</emphasis> Although the data
areas of NVRAM partitions are not required to have error checking, it is
strongly recommended that the system software implement robust data structures
and error checking. Loss of NVRAM structures due to data corruption can be
catastrophic, potentially leading to OS reinstallation and/or complete system
initialization.</para>
</section>

<section>
<title>Signatures</title>
<para>The <emphasis>signature</emphasis> field is used as the first level
of NVRAM partition identification. <xref linkend="dbdoclet.50569333_24820"/>
lists all the currently defined signature types and their ownership classes.
The ownership class determines the permission of a particular system software
component to create and/or modify NVRAM partitions and/or NVRAM partition
contents. All NVRAM partitions may be read by any system software component,
but the ownership class has exclusive write permission. Global ownership gives
read/write permission to all system software components. These restrictions are
made to minimize the possibility of corruption of NVRAM during update
<para>The <emphasis>signature</emphasis> field is used as the first level
of NVRAM partition identification. <xref linkend="dbdoclet.50569333_24820"/>
lists all the currently defined signature types and their ownership classes.
The ownership class determines the permission of a particular system software
component to create and/or modify NVRAM partitions and/or NVRAM partition
contents. All NVRAM partitions may be read by any system software component,
but the ownership class has exclusive write permission. Global ownership gives
read/write permission to all system software components. These restrictions are
made to minimize the possibility of corruption of NVRAM during update
activities.</para>
<para><emphasis role="bold">Hardware and Software Implementation Note:</emphasis> It is recommended that
NVRAM partitions be ordered on the signature field with the lowest value
signature NVRAM partition at the lowest NVRAM address (with the exception of
signature = 0x7F, free space). This will minimize the effect of NVRAM data
<para><emphasis role="bold">Hardware and Software Implementation Note:</emphasis> It is recommended that
NVRAM partitions be ordered on the signature field with the lowest value
signature NVRAM partition at the lowest NVRAM address (with the exception of
signature = 0x7F, free space). This will minimize the effect of NVRAM data
corruption on system operation.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569333_37259">
@ -183,9 +167,9 @@
<para> 1 byte</para>
</entry>
<entry>
<para> The <emphasis>signature</emphasis> field is used to
identify the NVRAM partition type and provide some level of checking for
overall NVRAM contamination. Signature assignments are given in
<para> The <emphasis>signature</emphasis> field is used to
identify the NVRAM partition type and provide some level of checking for
overall NVRAM contamination. Signature assignments are given in
<xref linkend="dbdoclet.50569333_24820"/>.</para>
</entry>
</row>
@ -197,11 +181,11 @@
<para> 1 byte</para>
</entry>
<entry>
<para> The <emphasis>checksum</emphasis> field is included to
provide a check on the validity of the header. The checksum covers the
<emphasis>signature</emphasis>, <emphasis>length</emphasis>, and
<emphasis>name</emphasis> fields and is calculated (on a byte by byte or equivalent
basis) by: add, and add 1 back to the sum if a carry resulted as demonstrated
<para> The <emphasis>checksum</emphasis> field is included to
provide a check on the validity of the header. The checksum covers the
<emphasis>signature</emphasis>, <emphasis>length</emphasis>, and
<emphasis>name</emphasis> fields and is calculated (on a byte by byte or equivalent
basis) by: add, and add 1 back to the sum if a carry resulted as demonstrated
with the following program listing.<programlisting><![CDATA[unsigned char sumcheck(bp,nbytes)
unsigned char *bp; /* buffer pointer */
unsigned int nbytes; /* number of bytes to sum */
@ -219,7 +203,7 @@ unsigned int nbytes; /* number of bytes to sum */
}
return (c_sum);
}]]></programlisting></para>
<para>This checksum algorithm guarantees 0 to be an impossible
<para>This checksum algorithm guarantees 0 to be an impossible
calculated value. A valid header cannot have a checksum of zero.</para>
</entry>
</row>
@ -231,13 +215,13 @@ unsigned int nbytes; /* number of bytes to sum */
<para> 2 bytes</para>
</entry>
<entry>
<para> The <emphasis>length</emphasis> field designates the
total length of the NVRAM partition, in 16-byte blocks, beginning with the
signature and ending with the last byte of the data area. A length of zero is
<para> The <emphasis>length</emphasis> field designates the
total length of the NVRAM partition, in 16-byte blocks, beginning with the
signature and ending with the last byte of the data area. A length of zero is
invalid.</para>
<para><emphasis role="bold">Software Implementation Note:</emphasis> The
<emphasis>length</emphasis> field must always provide valid offsets to the
next header since an invalid length effectively causes the loss of access to
<para><emphasis role="bold">Software Implementation Note:</emphasis> The
<emphasis>length</emphasis> field must always provide valid offsets to the
next header since an invalid length effectively causes the loss of access to
every NVRAM partition beyond it.</para>
</entry>
</row>
@ -249,18 +233,18 @@ unsigned int nbytes; /* number of bytes to sum */
<para> 12 bytes</para>
</entry>
<entry>
<para> The <emphasis>name</emphasis> field is a 12 byte string
(or a NULL-terminated string of less than 12 bytes) used to identify a
particular NVRAM partition within a signature group. In order to reduce the
likelihood of a naming conflict, each platform-specific or OS-specific NVRAM
partition name should be prefixed with a company name as specified under the
description of the &#x201C;name&#x201D; string in the
<emphasis><xref linkend="dbdoclet.50569387_45524"/>,</emphasis> that is, a company name string
in one of the three forms described in the reference, followed by a comma
(&#x201C;,&#x201D;). If the company name string is null, the name will be
<para> The <emphasis>name</emphasis> field is a 12 byte string
(or a NULL-terminated string of less than 12 bytes) used to identify a
particular NVRAM partition within a signature group. In order to reduce the
likelihood of a naming conflict, each platform-specific or OS-specific NVRAM
partition name should be prefixed with a company name as specified under the
description of the &#x201C;name&#x201D; string in the
<emphasis><xref linkend="dbdoclet.50569387_45524"/>,</emphasis> that is, a company name string
in one of the three forms described in the reference, followed by a comma
(&#x201C;,&#x201D;). If the company name string is null, the name will be
interpreted as &#x201C;other&#x201D;.</para>
<para>Before assigning a new name to a NVRAM partition, software
should scan the existing NVRAM partitions and ensure that an unwanted name
<para>Before assigning a new name to a NVRAM partition, software
should scan the existing NVRAM partitions and ensure that an unwanted name
conflict is not created.</para>
</entry>
</row>
@ -272,7 +256,7 @@ unsigned int nbytes; /* number of bytes to sum */
<para><emphasis>length</emphasis> minus 16 bytes</para>
</entry>
<entry>
<para> The structure of the <emphasis>data</emphasis> area is
<para> The structure of the <emphasis>data</emphasis> area is
controlled by the creator/owner of the NVRAM partition.</para>
</entry>
</row>
@ -366,8 +350,8 @@ unsigned int nbytes; /* number of bytes to sum */
<para> 0 to n</para>
</entry>
<entry>
<para> This signature is used to mark free space in the NVRAM
array. The <emphasis>name</emphasis> field of all signature 0x7F NVRAM
<para> This signature is used to mark free space in the NVRAM
array. The <emphasis>name</emphasis> field of all signature 0x7F NVRAM
partitions must be set to 0x7...77.</para>
</entry>
</row>
@ -390,8 +374,8 @@ unsigned int nbytes; /* number of bytes to sum */
</row>
<row>
<entry nameend="c5" namest="c1" align="left">
<para><emphasis role="bold">Note:</emphasis> Any signature not defined above is reserved, and
signatures 0x02, 0x50, 0x51, 0x52, 0x71, and 0x72 are reserved for legacy
<para><emphasis role="bold">Note:</emphasis> Any signature not defined above is reserved, and
signatures 0x02, 0x50, 0x51, 0x52, 0x71, and 0x72 are reserved for legacy
reasons.</para>
</entry>
</row>
@ -399,136 +383,136 @@ unsigned int nbytes; /* number of bytes to sum */
</tgroup>
</table>
</section>

<section>
<title>Architected NVRAM Partitions</title>

<section xml:id="dbdoclet.50569333_25869">
<title>System (0x70)</title>
<para>System NVRAM partitions are used for storing information
(typically, configuration variables) accessible to both OF and the OS. Refer to
<xref linkend="dbdoclet.50569368_91814"/> for the definition of the contents of the
<para>System NVRAM partitions are used for storing information
(typically, configuration variables) accessible to both OF and the OS. Refer to
<xref linkend="LoPAR.DeviceTree"/> for the definition of the contents of the
System NVRAM partition named <emphasis role="bold"><literal>common</literal></emphasis>.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Every system NVRAM must contain a System
<para>Every system NVRAM must contain a System
NVRAM partition with the NVRAM partition name = <emphasis role="bold"><literal>common</literal></emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Data in the <emphasis role="bold"><literal>common</literal></emphasis>
NVRAM partition must be stored as NULL-terminated strings of the form:
<emphasis>&lt;name&gt;=&lt;string&gt;</emphasis> and the
<emphasis>data</emphasis> area must be terminated with at least two NULL
<para>Data in the <emphasis role="bold"><literal>common</literal></emphasis>
NVRAM partition must be stored as NULL-terminated strings of the form:
<emphasis>&lt;name&gt;=&lt;string&gt;</emphasis> and the
<emphasis>data</emphasis> area must be terminated with at least two NULL
characters.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>All <emphasis>names</emphasis> used in
<para>All <emphasis>names</emphasis> used in
the <emphasis role="bold"><literal>common</literal></emphasis> NVRAM partition must be unique.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_25869"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Device and file specifications used in
the <emphasis role="bold"><literal>common</literal></emphasis> NVRAM partition must follow IEEE Std 1275
<para>Device and file specifications used in
the <emphasis role="bold"><literal>common</literal></emphasis> NVRAM partition must follow IEEE Std 1275
nomenclature conventions.</para>
</listitem>
</varlistentry>
</variablelist>

<section>
<title>System NVRAM Partition</title>
<para>The System NVRAM partition, with name = <emphasis role="bold"><literal>common</literal></emphasis>,
contains information that is accessible to both OF and OSs.
The contents of this NVRAM partition are represented in the OF device tree as
properties (i.e., (<emphasis>name</emphasis>, <emphasis>value</emphasis>)
pairs) in the <emphasis role="bold"><literal>/options</literal></emphasis> node. While OF is available, the
OS can alter the contents of these properties by using the
<emphasis>setprop</emphasis> client interface service. When OF is no longer available,
the OS can alter the contents of the System NVRAM partition itself, following
the rules below for the formats of the <emphasis>name</emphasis> and
<emphasis>value</emphasis>. Information is stored in the System NVRAM
partition as a sequence of (<emphasis>name</emphasis>,
<para>The System NVRAM partition, with name = <emphasis role="bold"><literal>common</literal></emphasis>,
contains information that is accessible to both OF and OSs.
The contents of this NVRAM partition are represented in the OF device tree as
properties (i.e., (<emphasis>name</emphasis>, <emphasis>value</emphasis>)
pairs) in the <emphasis role="bold"><literal>/options</literal></emphasis> node. While OF is available, the
OS can alter the contents of these properties by using the
<emphasis>setprop</emphasis> client interface service. When OF is no longer available,
the OS can alter the contents of the System NVRAM partition itself, following
the rules below for the formats of the <emphasis>name</emphasis> and
<emphasis>value</emphasis>. Information is stored in the System NVRAM
partition as a sequence of (<emphasis>name</emphasis>,
<emphasis>value</emphasis>) pairs in the following format: </para>
<para><emphasis>name = value</emphasis></para>
<para>where <emphasis>name</emphasis> follows the rules defined in
<xref linkend="dbdoclet.50569333_24970"/> and <emphasis>value</emphasis> follows the
rules defined in <xref linkend="dbdoclet.50569333_36194"/>. The end of the
<para>where <emphasis>name</emphasis> follows the rules defined in
<xref linkend="dbdoclet.50569333_24970"/> and <emphasis>value</emphasis> follows the
rules defined in <xref linkend="dbdoclet.50569333_36194"/>. The end of the
sequence of pairs is denoted by a NULL (0x00) byte. </para>

<section xml:id="dbdoclet.50569333_24970">
<title>Name</title>
<para>Since the data in the System NVRAM partition is an external
representation of properties of the <emphasis role="bold"><literal>/option</literal></emphasis> node, the
name component must follow the rules for <emphasis role="bold"><literal>property names</literal></emphasis>
<para>Since the data in the System NVRAM partition is an external
representation of properties of the <emphasis role="bold"><literal>/option</literal></emphasis> node, the
name component must follow the rules for <emphasis role="bold"><literal>property names</literal></emphasis>
as defined by Section 3.2.2.1.1 Property names of
<xref linkend="dbdoclet.50569387_45524"/>; i.e., a string of 1-31 printable
characters containing no uppercase characters or the characters
&#x201C;/&#x201D;, &#x201C;\&#x201D;, &#x201C;:&#x201D;, &#x201C;[&#x201C;,
&#x201C;]&#x201D; or &#x201C;@&#x201D;. In addition to these rules, a naming
convention is required for OS specific names to avoid name conflicts. Each such
name must begin with the OS vendor&#x2019;s OUI followed by a
&#x201C;,&#x201D;; e.g., aapl,<emphasis>xxx</emphasis> or
ibm,<emphasis>xxx</emphasis>. This introduces separate name spaces for each vendor in which
<xref linkend="dbdoclet.50569387_45524"/>; i.e., a string of 1-31 printable
characters containing no uppercase characters or the characters
&#x201C;/&#x201D;, &#x201C;\&#x201D;, &#x201C;:&#x201D;, &#x201C;[&#x201C;,
&#x201C;]&#x201D; or &#x201C;@&#x201D;. In addition to these rules, a naming
convention is required for OS specific names to avoid name conflicts. Each such
name must begin with the OS vendor&#x2019;s OUI followed by a
&#x201C;,&#x201D;; e.g., aapl,<emphasis>xxx</emphasis> or
ibm,<emphasis>xxx</emphasis>. This introduces separate name spaces for each vendor in which
it manages its own naming conventions. </para>
</section>

<section xml:id="dbdoclet.50569333_36194">
<title>Value </title>
<para>The value component of System NVRAM partition data can contain an
arbitrary number of bytes in the range 0x01 to 0xFF, terminated by a NULL
(0x00) byte. Bytes in the range 0x01 to 0xFE represent themselves. In order to
allow arbitrary byte data to be represented, an encoding is used to represent
strings of 0x00 or 0xFF bytes. This encoding uses the 0xFF byte as an escape,
<para>The value component of System NVRAM partition data can contain an
arbitrary number of bytes in the range 0x01 to 0xFF, terminated by a NULL
(0x00) byte. Bytes in the range 0x01 to 0xFE represent themselves. In order to
allow arbitrary byte data to be represented, an encoding is used to represent
strings of 0x00 or 0xFF bytes. This encoding uses the 0xFF byte as an escape,
indicating that the following byte is encoded as:</para>
<para>bnnnnnnn</para>
<para>where b, the most-significant bit, is 0 to represent a sequence of
0x00 bytes or 1 to represent a sequence of 0xFF bytes. nnnnnnn, the
least-significant 7 bits, is a binary number (in the range 0x01 to 0x7F) that
<para>where b, the most-significant bit, is 0 to represent a sequence of
0x00 bytes or 1 to represent a sequence of 0xFF bytes. nnnnnnn, the
least-significant 7 bits, is a binary number (in the range 0x01 to 0x7F) that
represents the number of repetitions of 0x00 or 0xFF. </para>
</section>

<section>
<title>OF Configuration Variables</title>
<para>OF configuration variables control the operation of OF. In addition
to the standard configuration variables defined in
<xref linkend="dbdoclet.50569387_45524"/>, other configuration variables are defined
in <xref linkend="dbdoclet.50569374_59715"/>. While such variables are stored in the System
NVRAM partition as described above, they have additional rules placed on the
format of the value component. Each configuration variable is also represented
by a user interface word (of the same name) that returns stack value(s) when
that word is evaluated. Each also has a platform defined default value; the
absence of a configuration variable in the System NVRAM partition indicates
that the value is set to its default value. The format of the external
representation of configuration variables, and their stack representation, is
defined by Section 7.4.4.1 Configuration Variables of
<xref linkend="dbdoclet.50569387_45524"/>; the format depends upon the data type of
the configuration variable. Whereas the internal storage format is not defined
by <xref linkend="dbdoclet.50569387_45524"/>, this architecture specifies them
as described below. The names of configuration variables are defined in <xref
<para>OF configuration variables control the operation of OF. In addition
to the standard configuration variables defined in
<xref linkend="dbdoclet.50569387_45524"/>, other configuration variables are defined
in <xref linkend="LoPAR.RTAS"/>. While such variables are stored in the System
NVRAM partition as described above, they have additional rules placed on the
format of the value component. Each configuration variable is also represented
by a user interface word (of the same name) that returns stack value(s) when
that word is evaluated. Each also has a platform defined default value; the
absence of a configuration variable in the System NVRAM partition indicates
that the value is set to its default value. The format of the external
representation of configuration variables, and their stack representation, is
defined by Section 7.4.4.1 Configuration Variables of
<xref linkend="dbdoclet.50569387_45524"/>; the format depends upon the data type of
the configuration variable. Whereas the internal storage format is not defined
by <xref linkend="dbdoclet.50569387_45524"/>, this architecture specifies them
as described below. The names of configuration variables are defined in <xref
linkend="dbdoclet.50569387_45524"/>, except as noted otherwise.</para>

<section>
<title>Boolean Configuration Variables </title>
<para>The value of a boolean configuration variable is represented in the
System NVRAM partition as the string &#x201C;true&#x201D; or
&#x201C;false&#x201D;. The following configuration variables are of type
<para>The value of a boolean configuration variable is represented in the
System NVRAM partition as the string &#x201C;true&#x201D; or
&#x201C;false&#x201D;. The following configuration variables are of type
boolean: </para>
<itemizedlist mark="none">
<listitem>
@ -563,9 +547,9 @@ unsigned int nbytes; /* number of bytes to sum */

<section>
<title>Integer Configuration Variables </title>
<para>The value of an integer configuration variable is represented in
the System NVRAM partition as a decimal number or a hexadecimal number preceded
by &#x201C;0x&#x201D;. The following configuration variables are of type
<para>The value of an integer configuration variable is represented in
the System NVRAM partition as a decimal number or a hexadecimal number preceded
by &#x201C;0x&#x201D;. The following configuration variables are of type
integer:</para>
<itemizedlist mark="none">
<listitem>
@ -600,14 +584,14 @@ unsigned int nbytes; /* number of bytes to sum */
</listitem>
</itemizedlist>
</section>

<section>
<title>String Configuration Variables</title>
<para>The value of a string configuration variable is represented in the
System NVRAM partition as the characters of the string. Where multiple
&#x201C;lines&#x201D; of text are represented, each line is terminated by a
carriage-return (0x0D), a line-feed (0x0A), or carriage-return, line-feed
sequence (0x0D, 0x0A). The following configuration variables are of type
<para>The value of a string configuration variable is represented in the
System NVRAM partition as the characters of the string. Where multiple
&#x201C;lines&#x201D; of text are represented, each line is terminated by a
carriage-return (0x0D), a line-feed (0x0A), or carriage-return, line-feed
sequence (0x0D, 0x0A). The following configuration variables are of type
string: </para>
<itemizedlist mark="none">
<listitem>
@ -657,8 +641,8 @@ unsigned int nbytes; /* number of bytes to sum */

<section>
<title>Byte Configuration Variables </title>
<para>The value of a bytes configuration variable is represented by an
arbitrary number of bytes, using the encoding escape for values of 0x00 and
<para>The value of a bytes configuration variable is represented by an
arbitrary number of bytes, using the encoding escape for values of 0x00 and
0xFF. The following configuration variables are of type bytes:</para>
<itemizedlist mark="none">
<listitem>
@ -671,89 +655,89 @@ unsigned int nbytes; /* number of bytes to sum */

<section xml:id="sec_disk_startup">
<title>DASD Spin-up Control</title>
<para> In order to reduce the boot time of platforms, a configuration
variable is defined to communicate from the platform to the OS to what extent
spin-up of hard disk drives can be overlapped. Disk drives generally draw more
current as the motors spin up to operating speed, thus the capacity of the
<para> In order to reduce the boot time of platforms, a configuration
variable is defined to communicate from the platform to the OS to what extent
spin-up of hard disk drives can be overlapped. Disk drives generally draw more
current as the motors spin up to operating speed, thus the capacity of the
power supply limits the ability to spin up drives simultaneously.</para>
<para>The configuration variable
<emphasis role="bold"><literal>ibm,dasd-spin-interval</literal></emphasis> indicates the minimum time, in seconds, that
must be allowed between initiating the spin-up of hard disk drives on the
platform. Presence of this variable potentially allows starting up a drive
prior to receiving completion status from a drive previously started. The
absence of this variable implies no platform knowledge regarding the capability
to overlap and, hence, the OS should wait for the appropriate device status
<para>The configuration variable
<emphasis role="bold"><literal>ibm,dasd-spin-interval</literal></emphasis> indicates the minimum time, in seconds, that
must be allowed between initiating the spin-up of hard disk drives on the
platform. Presence of this variable potentially allows starting up a drive
prior to receiving completion status from a drive previously started. The
absence of this variable implies no platform knowledge regarding the capability
to overlap and, hence, the OS should wait for the appropriate device status
before proceeding to subsequent drives (no overlap).</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_disk_startup"
<term><emphasis role="bold">R1-<xref linkend="sec_disk_startup"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>If a platform wants to overlap spinning
up it's hard disk drives to improve boot performance, it must create the
<emphasis role="bold"><literal>ibm,dasd-spin-interval</literal></emphasis> OF configuration variable in the
NVRAM signature 0x70 NVRAM partition named <emphasis role="bold"><literal>common</literal></emphasis> and set
it equal to an integer that represents the minimum time, in seconds, that must
<para>If a platform wants to overlap spinning
up it's hard disk drives to improve boot performance, it must create the
<emphasis role="bold"><literal>ibm,dasd-spin-interval</literal></emphasis> OF configuration variable in the
NVRAM signature 0x70 NVRAM partition named <emphasis role="bold"><literal>common</literal></emphasis> and set
it equal to an integer that represents the minimum time, in seconds, that must
be allowed between initiating the spin-up of drives on the platform.</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Firmware Implementation Note:</emphasis> The platform
should provide a user-friendly interface to this variable to allow for the
possibility of a user installing hard disks that do not conform to the original
<para><emphasis role="bold">Firmware Implementation Note:</emphasis> The platform
should provide a user-friendly interface to this variable to allow for the
possibility of a user installing hard disks that do not conform to the original
setting of the variable.</para>
</section>
</section>

<section xml:id="sec_free_space">
<title>Free Space (0x7F)</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_free_space"
<term><emphasis role="bold">R1-<xref linkend="sec_free_space"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>All unused NVRAM space must be included
<para>All unused NVRAM space must be included
in a signature = 0x7F Free Space NVRAM partition.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_free_space"
<term><emphasis role="bold">R1-<xref linkend="sec_free_space"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>All Free Space NVRAM partitions must have
<para>All Free Space NVRAM partitions must have
the <emphasis>name</emphasis> field set to 0x7...77.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>

<section xml:id="dbdoclet.50569333_13442">
<title>NVRAM Space Management</title>
<para>The only NVRAM partitions whose size an OS can modify are OS and Free
Space signature NVRAM partitions. As NVRAM partitions are created and modified
by an OS, it is likely that free space will become fragmented; free space
<para>The only NVRAM partitions whose size an OS can modify are OS and Free
Space signature NVRAM partitions. As NVRAM partitions are created and modified
by an OS, it is likely that free space will become fragmented; free space
consolidation may become necessary.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_13442"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_13442"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>An OS must not move or delete any NVRAM
<para>An OS must not move or delete any NVRAM
partition, except OS and Free Space signature NVRAM partitions. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_13442"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569333_13442"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The NVRAM partition header checksum must be
<para>The NVRAM partition header checksum must be
calculated as shown in <xref linkend="dbdoclet.50569333_37259"/>.</para>
</listitem>
</varlistentry>

46
LoPAR/ch_numa.xml → Platform/ch_numa.xml
Unescape Escape View File

@ -1,25 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569346_35960"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569346_35960"
version="5.0"
xml:lang="en">
<title>Non Uniform Memory Access (NUMA) Option</title>

<section>
@ -88,7 +72,7 @@
(processor, memory region, and IO slot) conveys information about the resources
statically assigned to the client program; and contains the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
property (see <xref linkend="dbdoclet.50569368_10192"/>). This property allows the client
property (see <xref linkend="LoPAR.RTAS"/>). This property allows the client
program to determine the associativity between any two of it&#x2019;s
resources. The greater the associativity the greater the expected performance
when using those two resources in a given operation.</para>
@ -112,7 +96,7 @@
information for the resources is not provided to prevent erroneous operation.
If the long term mapping changes the client program can be made aware of the
new associativity information using the <emphasis>ibm,update-properties</emphasis> RTAS call (See
<xref linkend="dbdoclet.50569332_40069"/>).</para>
<xref linkend="LoPAR.RTAS"/>).</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569346_19785">
@ -237,7 +221,7 @@
property byte 5 bit 0 has the value of zero, the
<emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis> property defines
reference points in the <emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
property (see <xref linkend="dbdoclet.50569368_41461"/>) which roughly correspond to
property (see <xref linkend="LoPAR.DeviceTree"/>) which roughly correspond to
traditional notions of platform topology constructs. It is important for the
user to realize that these reference points are not exact and their
characteristics vary among implementations. </para>
@ -297,7 +281,7 @@
<title>Dynamic Reconfiguration with Cross CEC I/O Drawers</title>
<para>Should the configuration change in such a way that the associativity
between an OS image&#x2019;s resources changes, the platform notifies the OS
via an event scan log. See <xref linkend="dbdoclet.50569337_37595"/>. </para>
via an event scan log. See <xref linkend="LoPAR.Error"/>. </para>

<variablelist>
<varlistentry>
@ -323,7 +307,7 @@
and the
<emphasis role="bold"><literal>&#x201C;ibm,current-associativity-domains&#x201D;</literal></emphasis>
properties in the <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the device tree (see
<xref linkend="dbdoclet.50569368_41461"/>).</para>
<xref linkend="LoPAR.DeviceTree"/>).</para>

<variablelist>
<varlistentry>
@ -335,7 +319,7 @@
<emphasis role="bold"><literal>&#x201C;ibm,max-associativity-domains&#x201D;</literal></emphasis>
and the
<emphasis role="bold"><literal>&#x201C;ibm,current-associativity-domains&#x201D;</literal></emphasis>
properties in
properties in
the <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the device tree.</para>
</listitem>
</varlistentry>
@ -359,7 +343,7 @@
preferred.</para>
<para>The OS and platform firmware negotiate their mutual support of the
PRRN option via the <emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis>
interface (See <xref linkend="dbdoclet.50569368_13649"/>). Should a partition be
interface (See <xref linkend="LoPAR.DeviceTree"/>). Should a partition be
migrated from a platform that did not support the PRRN option, the target
platform does not notify the partition&#x2019;s OS of any PRRN events and, when
possible avoids changing the affinity among the partition&#x2019;s resources.
@ -369,7 +353,7 @@
events.</para>
<para>A PRRN event is signaled via the RTAS <emphasis>event-scan</emphasis>
mechanism, which returns a Hot Plug Event message &#x201C;fixed
part&#x201D; (See <xref linkend="dbdoclet.50569337_28848"/>) indicating &#x201C;Platform
part&#x201D; (See <xref linkend="LoPAR.Error"/>) indicating &#x201C;Platform
Resource Reassignment&#x201D;. In response to the Hot Plug Event message, the
OS may call <emphasis>ibm,update-nodes</emphasis> to determine which resources
were reassigned, and then <emphasis>ibm,update-properties</emphasis> to obtain
@ -459,7 +443,7 @@
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description, Values (Described in <xref linkend="dbdoclet.50569337_75663"/>)</emphasis>
<emphasis role="bold">Description, Values (Described in <xref linkend="LoPAR.RTAS"/>)</emphasis>
</para>
</entry>
</row>

216
LoPAR/ch_introduction.xml → Platform/ch_platform_intro.xml
Unescape Escape View File

@ -1,146 +1,130 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569326_38341"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569326_38341"
version="5.0"
xml:lang="en">
<title>Introduction</title>

<para>This architecture specification provides a comprehensive computer
system platform-to-software interface definition, combined with minimum system
requirements, that enables the development of and software porting to a range
of compatible industry-standard computer systems from workstations through
servers. These systems are based on the requirements defined in
<xref linkend="dbdoclet.50569387_99718"/><footnote xml:id="pgfId-1000323"><para>The
term &#x201C;Processor Architecture&#x201D; (PA) is used throughout this
document to mean compliance with the requirements specified in
<xref linkend="dbdoclet.50569387_99718"/>.</para></footnote>. The definition supports
the development of both uniprocessor and multiprocessor system
<para>This architecture specification provides a comprehensive computer
system platform-to-software interface definition, combined with minimum system
requirements, that enables the development of and software porting to a range
of compatible industry-standard computer systems from workstations through
servers. These systems are based on the requirements defined in
<xref linkend="dbdoclet.50569387_99718"/><footnote xml:id="pgfId-1000323"><para>The
term &#x201C;Processor Architecture&#x201D; (PA) is used throughout this
document to mean compliance with the requirements specified in
<xref linkend="dbdoclet.50569387_99718"/>.</para></footnote>. The definition supports
the development of both uniprocessor and multiprocessor system
implementations.</para>
<para>A key attribute and benefit of this architecture is the ability of
platform developers to have degrees of freedom of implementation below the
level of architected interfaces and therefore have the opportunity for adding
unique value. This flexibility is achieved through architecture facilities
including: (1) device drivers; (2) Open Firmware (OF); (3)
Run-Time Abstraction Services (RTAS);
and (4) hardware abstraction layers. The role of items 1
and 4 are described in separate operating system (OS) documentation. The role
that items 2 and 3 play in this architecture will be described in subsequent
<para>A key attribute and benefit of this architecture is the ability of
platform developers to have degrees of freedom of implementation below the
level of architected interfaces and therefore have the opportunity for adding
unique value. This flexibility is achieved through architecture facilities
including: (1) device drivers; (2) Open Firmware (OF); (3)
Run-Time Abstraction Services (RTAS);
and (4) hardware abstraction layers. The role of items 1
and 4 are described in separate operating system (OS) documentation. The role
that items 2 and 3 play in this architecture will be described in subsequent
paragraphs and chapters.</para>
<para>This architecture combines leading-edge technologies to create a
superior computing platform. By design, it supports a wide range of computing
needs including personal productivity, engineering design, data management,
information analysis, education, desktop publishing, multimedia, entertainment,
and database, file, and application servers. This architecture effectively
leverages industry-standard I/O through the PCI bus. Systems based on this
architecture are expected to offer price/performance advantages and to address
<para>This architecture combines leading-edge technologies to create a
superior computing platform. By design, it supports a wide range of computing
needs including personal productivity, engineering design, data management,
information analysis, education, desktop publishing, multimedia, entertainment,
and database, file, and application servers. This architecture effectively
leverages industry-standard I/O through the PCI bus. Systems based on this
architecture are expected to offer price/performance advantages and to address
the expected growth in computing performance and functionality.</para>
<para><emphasis role="bold">Architecture Note:</emphasis> In modern platforms, designers may choose
between various PCI topology standards. This architecture uses the term
&#x201C;PCI&#x201D; as a general term to describe the most recent versions of
all forms of PCI standards including any approved Engineering Change Requests
(ECRs) against them. In cases where there are significant differences between
individual PCI standards, the following terminology is used to differentiate
<para><emphasis role="bold">Architecture Note:</emphasis> In modern platforms, designers may choose
between various PCI topology standards. This architecture uses the term
&#x201C;PCI&#x201D; as a general term to describe the most recent versions of
all forms of PCI standards including any approved Engineering Change Requests
(ECRs) against them. In cases where there are significant differences between
individual PCI standards, the following terminology is used to differentiate
between the PCI standards.</para>

<itemizedlist>
<itemizedlist>
<listitem>
<para>The term &#x201C;conventional PCI&#x201D; refers to behavior or
features that conform to the most recent version of the
<xref linkend="dbdoclet.50569387_65468"/>, including any approved ECRs against it.
<para>The term &#x201C;conventional PCI&#x201D; refers to behavior or
features that conform to the most recent version of the
<xref linkend="dbdoclet.50569387_65468"/>, including any approved ECRs against it.
</para>
</listitem>

<listitem>
<para>The term &#x201C;PCI-X&#x201D; refers to behavior or features that
conform to the most recent version of the
<para>The term &#x201C;PCI-X&#x201D; refers to behavior or features that
conform to the most recent version of the
<xref linkend="dbdoclet.50569387_26550"/>, including any approved ECRs against it.</para>
</listitem>

<listitem>
<para>The term &#x201C;PCI Express&#x201D; refers to behavior or features
that conform to the most recent version of the
<xref linkend="dbdoclet.50569387_66784"/> including any approved ECRs against it. In
addition, the terms &#x201C;bus,&#x201D; &#x201C;bridge&#x201D; and &#x201C;PCI
Host Bridge (PHB)&#x201D; used in relation to &#x201C;PCI&#x201D; throughout
this architecture may refer to a PCI Express &#x201C;link,&#x201D;
<para>The term &#x201C;PCI Express&#x201D; refers to behavior or features
that conform to the most recent version of the
<xref linkend="dbdoclet.50569387_66784"/> including any approved ECRs against it. In
addition, the terms &#x201C;bus,&#x201D; &#x201C;bridge&#x201D; and &#x201C;PCI
Host Bridge (PHB)&#x201D; used in relation to &#x201C;PCI&#x201D; throughout
this architecture may refer to a PCI Express &#x201C;link,&#x201D;
&#x201C;switch,&#x201D; and &#x201C;root complex&#x201D; respectively.</para>
</listitem>
</itemizedlist>

</itemizedlist>
<section>
<title>Platform Topology</title>
<para>To the experienced computer designer and system manufacturer, much of
the content of this architecture will be familiar. A typical desktop topology
is shown in <xref linkend="dbdoclet.50569326_34945"/>. This topology consists
of a single PA processor, volatile System Memory, and a single Host Bridge
providing a PCI Bus. The PCI Bus provides for connection of I/O adapters
(IOAs). See <xref linkend="dbdoclet.50569388_37308"/> for the definition of an
<para>To the experienced computer designer and system manufacturer, much of
the content of this architecture will be familiar. A typical desktop topology
is shown in <xref linkend="dbdoclet.50569326_34945"/>. This topology consists
of a single PA processor, volatile System Memory, and a single Host Bridge
providing a PCI Bus. The PCI Bus provides for connection of I/O adapters
(IOAs). See <xref linkend="dbdoclet.50569388_37308"/> for the definition of an
IOA.</para>
<para>A more complex general topology is shown in
<xref linkend="dbdoclet.50569326_34945"/>. All platforms consist of one or more PA
processors, a volatile System Memory separate from other subsystems, and a
number of IOAs, which may initiate transactions to System Memory. The
processors are linked over the primary processor bus/switch to each other, to
the System Memory, and to one or more Host Bridges. In general, IOAs do not
connect to the primary processor bus/switch. The Host Bridges connect to
secondary buses which have IOAs connected to them. In turn, one or more bus
bridges may be employed to tertiary buses (and beyond) with additional IOAs
connected to them. Typically, the bus speeds and throughput decrease and the
number of supportable loads increases as one progresses from the primary
<para>A more complex general topology is shown in
<xref linkend="dbdoclet.50569326_34945"/>. All platforms consist of one or more PA
processors, a volatile System Memory separate from other subsystems, and a
number of IOAs, which may initiate transactions to System Memory. The
processors are linked over the primary processor bus/switch to each other, to
the System Memory, and to one or more Host Bridges. In general, IOAs do not
connect to the primary processor bus/switch. The Host Bridges connect to
secondary buses which have IOAs connected to them. In turn, one or more bus
bridges may be employed to tertiary buses (and beyond) with additional IOAs
connected to them. Typically, the bus speeds and throughput decrease and the
number of supportable loads increases as one progresses from the primary
processor bus to more remote buses. </para>
<para>There are variations on these topologies, which are likely to occur
and are therefore worth describing below. This architecture describes
interfaces, not implementation. The logical software model must remain the
<para>There are variations on these topologies, which are likely to occur
and are therefore worth describing below. This architecture describes
interfaces, not implementation. The logical software model must remain the
same, even if the physical topology is different.</para>

<itemizedlist>
<itemizedlist>
<listitem>
<para>In a smaller platform, the Host Bridge and/or the memory and/or an
IOA may be integrated into a single chip. In this case, the topology would not
look like <xref linkend="dbdoclet.50569326_34945"/> from a chip point of view,
<para>In a smaller platform, the Host Bridge and/or the memory and/or an
IOA may be integrated into a single chip. In this case, the topology would not
look like <xref linkend="dbdoclet.50569326_34945"/> from a chip point of view,
but instead would be integrated onto the single chip.</para>
</listitem>

<listitem>
<para>In a larger platform, secondary buses may be implemented, with two
or more Host Bridges, as two or more parallel expansion buses for performance
reasons. Similarly, tertiary buses may be two or more parallel expansion buses
off each secondary bus. This is indicated by the ellipses near the Host Bridge
<para>In a larger platform, secondary buses may be implemented, with two
or more Host Bridges, as two or more parallel expansion buses for performance
reasons. Similarly, tertiary buses may be two or more parallel expansion buses
off each secondary bus. This is indicated by the ellipses near the Host Bridge
and the Bus Bridge.</para>
</listitem>

<listitem>
<para>In a high performance platform, with multiple processors and
multiple memoriea switch may be employed to allow multiple parallel accesses
by the processors to memory. The path through the switches would be decided by
the addressing of ths, a switch may be employed to allow multiple parallel accesses
by the processors to memory. The path through the switches would be decided by
<para>In a high performance platform, with multiple processors and
multiple memoriea switch may be employed to allow multiple parallel accesses
by the processors to memory. The path through the switches would be decided by
the addressing of ths, a switch may be employed to allow multiple parallel accesses
by the processors to memory. The path through the switches would be decided by
the addressing of the memory.</para>
</listitem>
</itemizedlist>
<para>Each of the following chapters provides information necessary to
successfully implement compliant systems. It is recommended that the reader
become thoroughly familiar with the contents of these chapters and their
references prior to beginning system or software development. It is anticipated
that standard chip sets will simplify the development of compliant
implementations consistent with the topologies shown below and will be
</itemizedlist>
<para>Each of the following chapters provides information necessary to
successfully implement compliant systems. It is recommended that the reader
become thoroughly familiar with the contents of these chapters and their
references prior to beginning system or software development. It is anticipated
that standard chip sets will simplify the development of compliant
implementations consistent with the topologies shown below and will be
available from third-party industry sources.</para>
<figure xml:id="dbdoclet.50569326_34945">
<title>Typical Desktop Topology</title>
@ -156,9 +140,9 @@
<imageobject role="fo"><imagedata contentdepth="100%" fileref="figures/PAPR-4.gif" format="GIF" scalefit="1" width="100%"/></imageobject>
</mediaobject>
</figure>
<para><emphasis role="bold">Note:</emphasis> To enable the implementation of a large number of I/O adapters in a large
system, the Host Bridge may be split into two pieces -- a Hub and a Bridge --
with the two connected by a cable, thus enabling the I/O adapters to be housed
<para><emphasis role="bold">Note:</emphasis> To enable the implementation of a large number of I/O adapters in a large
system, the Host Bridge may be split into two pieces -- a Hub and a Bridge --
with the two connected by a cable, thus enabling the I/O adapters to be housed
at a distance from the main processor enclosure.</para>
</section>
</chapter>

844
LoPAR/ch_processors_memory.xml → Platform/ch_processors_memory.xml
View File

File diff suppressed because it is too large Load Diff

350
LoPAR/ch_product_topology.xml → Platform/ch_product_topology.xml
Unescape Escape View File

@ -1,32 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569341_39268"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569341_39268"
version="5.0"
xml:lang="en">
<title>Product Topology</title>

<section xml:id="dbdoclet.50569341_34882">
<title>VPD and Location Code OF Properties</title>
<para>A set of OF properties is defined to facilitate asset protection and
RAS capabilities in LoPAR systems. The following properties are defined in
<xref linkend="dbdoclet.50569368_31220"/>):</para>
<xref linkend="LoPAR.DeviceTree"/>):</para>

<itemizedlist>
<listitem>
@ -153,7 +137,7 @@

<section xml:id="dbdoclet.50569341_23269">
<title>System Identification</title>
<para><xref linkend="dbdoclet.50569368_91814"/> provides properties in the
<para><xref linkend="LoPAR.DeviceTree"/> provides properties in the
&#x201C;OF Root Node&#x201D; section called <emphasis role="bold"><literal>&#x201C;system-id&#x201D;</literal></emphasis>
and<emphasis role="bold"><literal>&#x201C;model&#x201D;</literal></emphasis>.</para>

@ -1610,177 +1594,177 @@
</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>
</section>
<itemizedlist mark="none">
<listitem>
<para>U78CA.001.1234567-P1-C4-C1-S1-S2</para>
</listitem>
</itemizedlist>
</section>
</section>

@ -4723,7 +4707,7 @@
<para> Up to 56</para>
</entry>
<entry>
<para> Processor CoD Capacity Card Info per <xref linkend="dbdoclet.50569332_47931"/></para>
<para> Processor CoD Capacity Card Info per <xref linkend="LoPAR.RTAS"/></para>
</entry>
</row>
<row>
@ -4737,7 +4721,7 @@
<para> Up to 56</para>
</entry>
<entry>
<para> Memory CoD Capacity Card Info per <xref linkend="dbdoclet.50569332_47931"/></para>
<para> Memory CoD Capacity Card Info per <xref linkend="LoPAR.RTAS"/></para>
</entry>
</row>
<row>

442
LoPAR/ch_smp.xml → Platform/ch_smp.xml
Unescape Escape View File

@ -1,182 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569340_14972"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569340_14972"
version="5.0"
xml:lang="en">
<title>The Symmetric Multiprocessor Option</title>

<para>This architecture supports the implementation of symmetric
multiprocessor (SMP) systems as an optional feature. This Chapter provides
information concerning the design and programming of such systems. For SMP OF
binding information, see <xref linkend="dbdoclet.50569368_56107"/>.</para>
<para>SMP systems differ from uniprocessors in a number of ways. These
differences are not all covered in this chapter. Other chapters that cover
<para>This architecture supports the implementation of symmetric
multiprocessor (SMP) systems as an optional feature. This Chapter provides
information concerning the design and programming of such systems. For SMP OF
binding information, see <xref linkend="LoPAR.DeviceTree"/>.</para>
<para>SMP systems differ from uniprocessors in a number of ways. These
differences are not all covered in this chapter. Other chapters that cover
SMP-related topics include:</para>

<itemizedlist>
<itemizedlist>
<listitem>
<para>Non-processor-related initialization and other requirements:
<para>Non-processor-related initialization and other requirements:
<xref linkend="dbdoclet.50569327_31987"/></para>
</listitem>

<listitem>
<para>Interrupts: <xref linkend="dbdoclet.50569331_37856"/></para>
</listitem>

<listitem>
<para>Error handling: <xref linkend="dbdoclet.50569337_37595"/></para>
<para>Error handling: <xref linkend="LoPAR.Error"/></para>
</listitem>
</itemizedlist>
</itemizedlist>

<para>Many other general characteristics of SMPs&#x2014;such as
interprocessor communication, load/store ordering, and cache
coherence&#x2014;are defined in <xref linkend="dbdoclet.50569387_99718"/>.
Requirements and recommendations for system organization and time base synchronization are
<para>Many other general characteristics of SMPs&#x2014;such as
interprocessor communication, load/store ordering, and cache
coherence&#x2014;are defined in <xref linkend="dbdoclet.50569387_99718"/>.
Requirements and recommendations for system organization and time base synchronization are
discussed here, along with SMP-specific aspects of the boot process.</para>
<para>SMP platforms require SMP-specific OS support. An OS supporting only
uniprocessor platforms
may not be usable on an SMP, even when an SMP platform has only a single
processor installed; conversely, an SMP-supporting OS may not be usable on a
uniprocessor. It is, however, a requirement that uniprocessor OSs be able to
run on one-processor SMPs, and that SMP-enabled OSs also run on uniprocessors.
<para>SMP platforms require SMP-specific OS support. An OS supporting only
uniprocessor platforms
may not be usable on an SMP, even when an SMP platform has only a single
processor installed; conversely, an SMP-supporting OS may not be usable on a
uniprocessor. It is, however, a requirement that uniprocessor OSs be able to
run on one-processor SMPs, and that SMP-enabled OSs also run on uniprocessors.
See the next section.</para>

<section xml:id="dbdoclet.50569340_29104">
<title>SMP System Organization</title>
<para>This chapter only addresses SMP multiprocessor platforms. This is a
computer system in which multiple processors equally share functional and
timing access to and control over all other system components, including memory
and I/O, as defined in the requirements below. Other
multiprocessor organizations (&#x201C;asymmetric
multiprocessors,&#x201D; &#x201C; attached
processors,&#x201D; etc.) are not included in this architecture. These might,
for example, include systems in which only one processor can perform I/O
operations; or in which processors have private memory that is not accessible
<para>This chapter only addresses SMP multiprocessor platforms. This is a
computer system in which multiple processors equally share functional and
timing access to and control over all other system components, including memory
and I/O, as defined in the requirements below. Other
multiprocessor organizations (&#x201C;asymmetric
multiprocessors,&#x201D; &#x201C; attached
processors,&#x201D; etc.) are not included in this architecture. These might,
for example, include systems in which only one processor can perform I/O
operations; or in which processors have private memory that is not accessible
by other processors. </para>
<para>Requirements <xref linkend="dbdoclet.50569340_73893"/> through
<xref linkend="dbdoclet.50569340_79137"/>, further require that all processors
be of (nearly) equal speed, type, cache characteristics, etc. Requirements for
optional non-uniform multiprocessor platforms are found in
<para>Requirements <xref linkend="dbdoclet.50569340_73893"/> through
<xref linkend="dbdoclet.50569340_79137"/>, further require that all processors
be of (nearly) equal speed, type, cache characteristics, etc. Requirements for
optional non-uniform multiprocessor platforms are found in
<xref linkend="dbdoclet.50569346_35960"/>.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569340_80907">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>OSs that do not explicitly support the SMP option must support
<para>OSs that do not explicitly support the SMP option must support
SMP-enabled platforms, actively using only one processor. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor
<para><emphasis role="bold">For the Symmetric Multiprocessor
option:</emphasis> SMP OSs must support uniprocessor platforms.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor
option:</emphasis> The extensions defined in
<xref linkend="dbdoclet.50569368_56107"/>, and the SMP support section of the RTAS
specifications (see <xref linkend="dbdoclet.50569332_36251"/>) must be implemented.</para>
<para><emphasis role="bold">For the Symmetric Multiprocessor
option:</emphasis> The extensions defined in
<xref linkend="LoPAR.DeviceTree"/>, and the SMP support section of the RTAS
specifications (see <xref linkend="LoPAR.RTAS"/>) must be implemented.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_73893">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor or Power Management
option:</emphasis> All processors in the configuration must have equal
functional access and &#x201C;quasi-equal&#x201D;
timing access to all of system memory,
including other processors&#x2019; caches, via cache coherence.
&#x201C;Quasi-equal&#x201D; means that the time required for processors to
access memory is sufficiently close to being equal that all software can ignore
the difference without a noticeable negative impact on system performance; and
<para><emphasis role="bold">For the Symmetric Multiprocessor or Power Management
option:</emphasis> All processors in the configuration must have equal
functional access and &#x201C;quasi-equal&#x201D;
timing access to all of system memory,
including other processors&#x2019; caches, via cache coherence.
&#x201C;Quasi-equal&#x201D; means that the time required for processors to
access memory is sufficiently close to being equal that all software can ignore
the difference without a noticeable negative impact on system performance; and
no software is expected to profitably exploit the difference in timing. </para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_25908">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
All processors in the configuration must have equal functional and
&#x201C;quasi-equal&#x201D;
timing access to all I/O devices and IOAs.
&#x201C;Quasi-equal&#x201D; is defined as in Requirement <xref linkend="dbdoclet.50569340_73893"/>,
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
All processors in the configuration must have equal functional and
&#x201C;quasi-equal&#x201D;
timing access to all I/O devices and IOAs.
&#x201C;Quasi-equal&#x201D; is defined as in Requirement <xref linkend="dbdoclet.50569340_73893"/>,
above, with I/O access replacing memory access for this case. </para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_63554">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
SMP OSs must at least support SMPs with the same PVR contents and speed. The
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
SMP OSs must at least support SMPs with the same PVR contents and speed. The
PVR contents includes both the PVN and the revision number.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_79137">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
All caches at the same hierarchical level must have the same OF properties.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_12670">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>Hardware for SMPs must provide a means for synchronizing all the
time bases of all the processors in the platform, for use by platform firmware.
See <xref linkend="dbdoclet.50569332_36251"/>. This is for purposes of clock synchronization
<para>Hardware for SMPs must provide a means for synchronizing all the
time bases of all the processors in the platform, for use by platform firmware.
See <xref linkend="LoPAR.RTAS"/>. This is for purposes of clock synchronization
at initialization and at times when the processor loses time base state.</para>
</listitem>
</varlistentry>

<varlistentry xml:id="dbdoclet.50569340_88608">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569340_29104"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>The platform must initialize and maintain the synchronization of
the time bases and timers of all platform processors such that; for any code
sequence &#x201C;C&#x201D;, run between any two platform processors
&#x201C;A&#x201D; and &#x201C;B&#x201D;, where the reading of the time base or
timer in processor &#x201C;A&#x201D; can be architecturally guaranteed to have
happened later in time than the reading of the time base or timer in processor
&#x201C;B&#x201D;, the value of the time base read by processor
&#x201C;A&#x201D; is greater than or equal to the value of the time base read
<para>The platform must initialize and maintain the synchronization of
the time bases and timers of all platform processors such that; for any code
sequence &#x201C;C&#x201D;, run between any two platform processors
&#x201C;A&#x201D; and &#x201C;B&#x201D;, where the reading of the time base or
timer in processor &#x201C;A&#x201D; can be architecturally guaranteed to have
happened later in time than the reading of the time base or timer in processor
&#x201C;B&#x201D;, the value of the time base read by processor
&#x201C;A&#x201D; is greater than or equal to the value of the time base read
by processor &#x201C;B&#x201D;.</para>
</listitem>
</varlistentry>
@ -184,204 +168,204 @@

<para><emphasis role="bold">Software Implementation Notes:</emphasis></para>

<orderedlist>
<orderedlist>
<listitem>
<para>Requirement <xref linkend="dbdoclet.50569340_80907"/> has
implications on the design of uniprocessor OSs, particularly regarding the
handling of interrupts. See the sections that follow, particularly
<para>Requirement <xref linkend="dbdoclet.50569340_80907"/> has
implications on the design of uniprocessor OSs, particularly regarding the
handling of interrupts. See the sections that follow, particularly
<xref linkend="dbdoclet.50569340_57956"/>.</para>
</listitem>

<listitem>
<para>While Requirement <xref linkend="dbdoclet.50569340_63554"/> does
not require this, OSs are encouraged to support processors of the same type but
different PVR contents as long as their programming models are
<para>While Requirement <xref linkend="dbdoclet.50569340_63554"/> does
not require this, OSs are encouraged to support processors of the same type but
different PVR contents as long as their programming models are
compatible.</para>
</listitem>

<listitem>
<para>Because of performance penalties associated with inter-processor
synchronization, the weakest synchronization primitive that produces correct
operation should be used. For example, <emphasis>eieio</emphasis> can often be
used as part of a sequence that unlocks a data structure, rather than the
<para>Because of performance penalties associated with inter-processor
synchronization, the weakest synchronization primitive that produces correct
operation should be used. For example, <emphasis>eieio</emphasis> can often be
used as part of a sequence that unlocks a data structure, rather than the
higher-overhead but more general <emphasis>sync</emphasis> instruction. </para>
</listitem>
</orderedlist>
</orderedlist>

<para><emphasis role="bold">Hardware Implementation Notes:</emphasis></para>
<orderedlist>
<orderedlist>
<listitem>
<para>Particularly when used as servers, SMP systems make heavy demands
on the I/O and memory subsystems. Therefore, it is strongly recommended that
the I/O and memory subsystem of an SMP platform should either be expandable as
additional processors are added, or else designed to handle the load of the
<para>Particularly when used as servers, SMP systems make heavy demands
on the I/O and memory subsystems. Therefore, it is strongly recommended that
the I/O and memory subsystem of an SMP platform should either be expandable as
additional processors are added, or else designed to handle the load of the
maximum system configuration.</para>
</listitem>

<listitem xml:id="dbdoclet.50569340_marker-513176">
<para>Defining an exact numeric threshold for
&#x201C;quasi-equal&#x201D; is not feasible because it depends on the
application, compiler, subsystem, and OS software that the system is to run. It
is highly likely that a wider range of timing differences can be absorbed in
I/O access time than in memory access time. An illustrative example that is
deliberately far from an upper bound: A 2% timing difference is certainly
quasi-equal by this definition. While significantly larger timing differences
are undoubtedly also quasi-equal, more conclusive statements must be the
<para>Defining an exact numeric threshold for
&#x201C;quasi-equal&#x201D; is not feasible because it depends on the
application, compiler, subsystem, and OS software that the system is to run. It
is highly likely that a wider range of timing differences can be absorbed in
I/O access time than in memory access time. An illustrative example that is
deliberately far from an upper bound: A 2% timing difference is certainly
quasi-equal by this definition. While significantly larger timing differences
are undoubtedly also quasi-equal, more conclusive statements must be the
province of the OS and other software.</para>
</listitem>
</orderedlist>
</orderedlist>
</section>

<section xml:id="dbdoclet.50569340_19429">
<title>An SMP Boot Process</title>
<para>Booting
an SMP entails considerations not present when booting a
uniprocessor. This section indicates those considerations by describing a way
in which an SMP system can be booted. It does not pretend to describe
&#x201C;the&#x201D; way to boot an SMP, since there are a wide variety of ways
to do this, depending on engineering choices that can differ from platform to
platform. To illustrate the possibilities, several variations on the SMP
<para>Booting
an SMP entails considerations not present when booting a
uniprocessor. This section indicates those considerations by describing a way
in which an SMP system can be booted. It does not pretend to describe
&#x201C;the&#x201D; way to boot an SMP, since there are a wide variety of ways
to do this, depending on engineering choices that can differ from platform to
platform. To illustrate the possibilities, several variations on the SMP
booting theme will be described after the initial description.</para>
<para>This section concentrates solely on SMP-related issues, and ignores a
number of other initialization issues such as hibernation and suspension. See
<xref linkend="dbdoclet.50569327_34213"/> for a discussion of those other
<para>This section concentrates solely on SMP-related issues, and ignores a
number of other initialization issues such as hibernation and suspension. See
<xref linkend="dbdoclet.50569327_34213"/> for a discussion of those other
issues. </para>

<section xml:id="dbdoclet.50569340_33673">
<title>SMP-Safe Boot</title>
<para>The basic booting process described here is called
&#x201C;SMP-Safe&#x201D; because it tolerates the presence of multiple
<para>The basic booting process described here is called
&#x201C;SMP-Safe&#x201D; because it tolerates the presence of multiple
processors, but does not exploit them. This process proceeds as follows: </para>

<orderedlist>
<orderedlist>
<listitem>
<para>At power on, one or more finite state machines (FSMs) built into
the system hardware initialize each processor independently. FSMs also perform
basic initialization of other system elements, such as the memory and interrupt
<para>At power on, one or more finite state machines (FSMs) built into
the system hardware initialize each processor independently. FSMs also perform
basic initialization of other system elements, such as the memory and interrupt
controllers. </para>
</listitem>

<listitem>
<para>After the FSM initialization of each processor concludes, it
begins execution at a location in ROM that the FSM has specified. This is the
start of execution of the system firmware that eventually provides the OF
<para>After the FSM initialization of each processor concludes, it
begins execution at a location in ROM that the FSM has specified. This is the
start of execution of the system firmware that eventually provides the OF
interfaces to the OS. </para>
</listitem>

<listitem xml:id="dbdoclet.50569340_44228">
<para>One of the first things that firmware does is establish one of the processors as the
<emphasis>master</emphasis>: The
<emphasis>master</emphasis> is a single processor which
continues with the rest of the booting process; all the others are placed in a
<emphasis>stopped</emphasis> state. A processor in this
<emphasis>stopped</emphasis> state is out of the picture; it does nothing that affects
the state of the system and will continue to be in that state until awakened by
some outside force, such as an inter-processor interrupt (IPI).<footnote xml:id="pgfId-242214"><para>Another
characteristic of the <emphasis>stopped</emphasis> state,
defined in <xref linkend="dbdoclet.50569374_59715"/>, is that the
processor remembers nothing of its prior life when placed in a
<emphasis>stopped</emphasis> state; this distinguishes it from the
<emphasis>idle</emphasis> state. That isn&#x2019;t strictly necessary for this booting
process; <emphasis>idle</emphasis> could have been used. However, since the
non-<emphasis>master</emphasis> processor must be in the
<emphasis>stopped</emphasis> state when the OS is started,
<para>One of the first things that firmware does is establish one of the processors as the
<emphasis>master</emphasis>: The
<emphasis>master</emphasis> is a single processor which
continues with the rest of the booting process; all the others are placed in a
<emphasis>stopped</emphasis> state. A processor in this
<emphasis>stopped</emphasis> state is out of the picture; it does nothing that affects
the state of the system and will continue to be in that state until awakened by
some outside force, such as an inter-processor interrupt (IPI).<footnote xml:id="pgfId-242214"><para>Another
characteristic of the <emphasis>stopped</emphasis> state,
defined in <xref linkend="LoPAR.RTAS"/>, is that the
processor remembers nothing of its prior life when placed in a
<emphasis>stopped</emphasis> state; this distinguishes it from the
<emphasis>idle</emphasis> state. That isn&#x2019;t strictly necessary for this booting
process; <emphasis>idle</emphasis> could have been used. However, since the
non-<emphasis>master</emphasis> processor must be in the
<emphasis>stopped</emphasis> state when the OS is started,
<emphasis>stopped</emphasis> might as well be used.</para></footnote></para>
<para>One way to choose the <emphasis>master</emphasis> is to include a special register
at a fixed address in the memory controller. That special register has the
<para>One way to choose the <emphasis>master</emphasis> is to include a special register
at a fixed address in the memory controller. That special register has the
following properties: </para>

<itemizedlist>
<itemizedlist>
<listitem>
<para>The FSM initializing the memory controller sets this
<para>The FSM initializing the memory controller sets this
register&#x2019;s contents to 0 (zero). </para>
</listitem>

<listitem>
<para>The first time that register is read, it returns the value 0 and
then sets its own contents to non-zero. This is performed as an atomic
operation; if two or more processors attempt to read the register at the same
time, exactly one of them will get the 0 and the rest will get a non-zero
<para>The first time that register is read, it returns the value 0 and
then sets its own contents to non-zero. This is performed as an atomic
operation; if two or more processors attempt to read the register at the same
time, exactly one of them will get the 0 and the rest will get a non-zero
value. </para>
</listitem>

<listitem>
<para>After the first attempt, all attempts to read that
<para>After the first attempt, all attempts to read that
register&#x2019;s contents return a non-zero value. </para>
</listitem>
</itemizedlist>
</itemizedlist>

<para>The <emphasis>master</emphasis> is then picked by having all the
processors read from that special register. Exactly one of them will receive a
<para>The <emphasis>master</emphasis> is then picked by having all the
processors read from that special register. Exactly one of them will receive a
0 and thereby become the <emphasis>master</emphasis>. </para>
<para>Note that the operation of choosing the
<emphasis>master</emphasis> cannot be done using the PA memory locking instructions,
since at this point in the boot process the memory is not initialized. The
advantage to using a register in the memory controller is that system bus
serialization can be used to automatically provide the required
<para>Note that the operation of choosing the
<emphasis>master</emphasis> cannot be done using the PA memory locking instructions,
since at this point in the boot process the memory is not initialized. The
advantage to using a register in the memory controller is that system bus
serialization can be used to automatically provide the required
atomicity.</para>
</listitem>

<listitem>
<para>The <emphasis>master</emphasis> chosen in step
<xref linkend="dbdoclet.50569340_44228"/> then proceeds to do the remainder of the
system initialization. This includes, for example, the remainder of Power-On
Self Test, initialization of OF, discovery of devices and construction of the
OF device tree, loading the OS, starting it, and so on. Since one processor is
performing all these functions, and the rest are in a state where they are not
affecting anything, code that is at least very close to the uniprocessor code
can be used for all of this (but see <xref linkend="dbdoclet.50569340_57956"/>
<para>The <emphasis>master</emphasis> chosen in step
<xref linkend="dbdoclet.50569340_44228"/> then proceeds to do the remainder of the
system initialization. This includes, for example, the remainder of Power-On
Self Test, initialization of OF, discovery of devices and construction of the
OF device tree, loading the OS, starting it, and so on. Since one processor is
performing all these functions, and the rest are in a state where they are not
affecting anything, code that is at least very close to the uniprocessor code
can be used for all of this (but see <xref linkend="dbdoclet.50569340_57956"/>
below).</para>
</listitem>

<listitem>
<para>The OS begins execution on the single
<emphasis>master</emphasis> processor. It uses the OF Client Interface
Services to start each of the other processors, taking them out of the
<para>The OS begins execution on the single
<emphasis>master</emphasis> processor. It uses the OF Client Interface
Services to start each of the other processors, taking them out of the
<emphasis>stopped</emphasis> state and setting them loose on the SMP OS code.</para>
<para>This completes the example SMP boot process. Variations are
discussed beginning at <xref linkend="dbdoclet.50569340_69262"/>. Before
discussing those variations, an element of the system initialization not
<para>This completes the example SMP boot process. Variations are
discussed beginning at <xref linkend="dbdoclet.50569340_69262"/>. Before
discussing those variations, an element of the system initialization not
discussed above will be covered.</para>
</listitem>
</orderedlist>
</orderedlist>

</section>

<section xml:id="dbdoclet.50569340_57956">
<title>Finding the Processor Configuration</title>
<para>Unlike uniprocessor initialization, SMP initialization must also
discover the number and identities of the processors installed in the system.
&#x201C;Identity&#x201D; means the interrupt address of each processor as seen
by the interrupt controller; without that information, a processor cannot reset
interrupts directed at it. This identity is determined by board wiring: The
processor attached to the &#x201C;processor 0&#x201D; wire from the interrupt
controller has identity 0. For information about how this identity is used, see
<xref linkend="dbdoclet.50569368_56107"/>.</para>
<para>The method used by a platform to identify its processors is
dependent upon the platform hardware design and may be based upon service
processor information, identification registers, inter-processor interrupts, or
<para>Unlike uniprocessor initialization, SMP initialization must also
discover the number and identities of the processors installed in the system.
&#x201C;Identity&#x201D; means the interrupt address of each processor as seen
by the interrupt controller; without that information, a processor cannot reset
interrupts directed at it. This identity is determined by board wiring: The
processor attached to the &#x201C;processor 0&#x201D; wire from the interrupt
controller has identity 0. For information about how this identity is used, see
<xref linkend="LoPAR.DeviceTree"/>.</para>
<para>The method used by a platform to identify its processors is
dependent upon the platform hardware design and may be based upon service
processor information, identification registers, inter-processor interrupts, or
other novel techniques.</para>
</section>

<section xml:id="dbdoclet.50569340_69262">
<title>SMP-Efficient Boot </title>
<para>The booting
process as described so far tolerates the existence of multiple processors but
does not attempt to exploit them. It is possible that the booting process can
be sped up by actively using multiple processors simultaneously. In that case,
the pick-a-<emphasis>master</emphasis> technique must still be
used to perform sufficient initialization that other inter-processor
coordination facilities&#x2014;in-memory locks and IPIs&#x2014;can be used.
Once that is accomplished, normal parallel SMP programming techniques can be
<para>The booting
process as described so far tolerates the existence of multiple processors but
does not attempt to exploit them. It is possible that the booting process can
be sped up by actively using multiple processors simultaneously. In that case,
the pick-a-<emphasis>master</emphasis> technique must still be
used to perform sufficient initialization that other inter-processor
coordination facilities&#x2014;in-memory locks and IPIs&#x2014;can be used.
Once that is accomplished, normal parallel SMP programming techniques can be
used within the initialization process itself.</para>
</section>

<section>
<title>Use of a Service Processor</title>
<para>A system might contain a service processor that is distinct from the processors
that form the SMP. If that service processor has suitably intimate access to
and control over each of the SMP processors, it can perform the operations of
choosing a <emphasis>master</emphasis> and discovering the SMP processor
<para>A system might contain a service processor that is distinct from the processors
that form the SMP. If that service processor has suitably intimate access to
and control over each of the SMP processors, it can perform the operations of
choosing a <emphasis>master</emphasis> and discovering the SMP processor
configuration.</para>
<para>&#xA0;</para>
</section>

149
LoPAR/ch_system_reqs.xml → Platform/ch_system_reqs.xml
Unescape Escape View File

@ -1,25 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569327_31987"
version="5.0"
xml:lang="en">
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:id="dbdoclet.50569327_31987"
version="5.0"
xml:lang="en">
<title>System Requirements</title>

<para>This chapter gives an operational overview of LoPAR systems and
@ -347,7 +331,7 @@
<section xml:id="dbdoclet.50569327_28943">
<title>Locate an OS Boot Image </title>
<para>The OS boot image is located as described in
<xref linkend="dbdoclet.50569368_91814"/>. A device and filename can be specified directly
<xref linkend="LoPAR.DeviceTree"/>. A device and filename can be specified directly
from the command interpreter (the <emphasis>boot</emphasis> command) or OF
will locate the image through an automatic boot process controlled by
configuration variables. Once a boot image is located, the device path is set
@ -361,7 +345,7 @@
<emphasis role="bold"><literal>boot-device</literal></emphasis> entries that the platform processes.</para>
<para>If multi-boot (multiple bootable OSs residing on the same platform) is supported,
a configuration variable instructs the firmware to display a multi-boot menu
from which the OS and bootpath are selected. See <xref linkend="dbdoclet.50569368_91814"/>
from which the OS and bootpath are selected. See <xref linkend="LoPAR.DeviceTree"/>
for information relating to the multiboot process.</para>

<variablelist>
@ -384,10 +368,10 @@

<section xml:id="dbdoclet.50569327_26247">
<title>Boot Process</title>
<para>The boot process is described in <xref linkend="dbdoclet.50569368_91814"/>.
<para>The boot process is described in <xref linkend="LoPAR.DeviceTree"/>.
Steps in the process are reviewed here, but the
authoritative and complete description of the process is included in
<xref linkend="dbdoclet.50569368_91814"/>. <xref linkend="dbdoclet.50569327_17087"/> is a
<xref linkend="LoPAR.DeviceTree"/>. <xref linkend="dbdoclet.50569327_17087"/> is a
depiction of the boot flow showing the action of the f1, f5, and f6 function
keys. The figure should only be used as an aid in understanding the
requirements for LoPAR systems.</para>
@ -447,7 +431,7 @@
<para>Once the boot prompt is displayed, the System Management Services
(SMS) menu can be invoked. SMS provides a user interface for utilities,
configuration, and the Multiboot Menu (as introduced in
<xref linkend="dbdoclet.50569368_91814"/>) for boot/install and the OF command
<xref linkend="LoPAR.DeviceTree"/>) for boot/install and the OF command
interpreter.</para>
<para>The Multiboot menu is formatted so that block devices that
currently contain boot information are most easily selected by the user.
@ -737,7 +721,7 @@
<emphasis role="bold"><literal>diag-device</literal></emphasis>
configuration variables must include the standard block device
<literal>bootinfo.txt</literal> file specification as documented in
<xref linkend="dbdoclet.50569368_91814"/> (<literal>\ppc\bootinfo.txt</literal>).</para>
<xref linkend="LoPAR.DeviceTree"/> (<literal>\ppc\bootinfo.txt</literal>).</para>
</listitem>
</varlistentry>
</variablelist>
@ -745,7 +729,7 @@

<section xml:id="dbdoclet.50569327_20641">
<title>Tape Boot</title>
<para>Boot from tape is defined in <xref linkend="dbdoclet.50569368_91814"/>.</para>
<para>Boot from tape is defined in <xref linkend="LoPAR.DeviceTree"/>.</para>
</section>

<section xml:id="sec_network_boot">
@ -913,7 +897,7 @@ ELSE
the platform using the <emphasis>ibm,manage-storage-preservation</emphasis>
RTAS call if it wants the contents of the storage preserved across client boot
cycles (see also "Managing Storage Preservations" in
<xref linkend="dbdoclet.50569332_28221"/> specification). The architectural intent of this
<xref linkend="LoPAR.RTAS"/> specification). The architectural intent of this
facility is to enable client programs to emulate persistent storage. This is
done by a client program registering preservable LMBs. Then, after a subsequent
boot cycle (perhaps due to error or impending power loss) the presence of the
@ -1045,7 +1029,7 @@ ELSE
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569327_22507"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms must implement OF as defined in <xref linkend="dbdoclet.50569368_91814"/>.</para>
<para>Platforms must implement OF as defined in <xref linkend="LoPAR.DeviceTree"/>.</para>
</listitem>
</varlistentry>

@ -1069,7 +1053,7 @@ ELSE
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Platforms must implement the Run-Time Abstraction Services (RTAS) as described in
<xref linkend="dbdoclet.50569332_13537"/>.</para>
<xref linkend="LoPAR.RTAS"/>.</para>
</listitem>
</varlistentry>

@ -1154,7 +1138,7 @@ ELSE
<section>
<title>Tape Install</title>
<para>The OF definition of installation from tape is defined in
<xref linkend="dbdoclet.50569368_91814"/>.</para>
<xref linkend="LoPAR.DeviceTree"/>.</para>
</section>

<section xml:id="sec_network_install">
@ -1183,7 +1167,7 @@ ELSE
will run on other vendors&#x2019; platforms which might not have permission to
use AIX diagnostics, the <emphasis role="bold"><literal>&#x201C;ibm,aix-diagnostics&#x201D;</literal></emphasis>
property indicates that AIX diagnostics are permitted (see "Root
Node Properties" in <xref linkend="dbdoclet.50569337_42315"/>).</para>
Node Properties" in <xref linkend="LoPAR.DeviceTree"/>).</para>

<variablelist>
<varlistentry>
@ -1200,14 +1184,15 @@ ELSE

<para><emphasis role="bold">Software Implementation Note:</emphasis> Each OS may implement an OS-specific
run-time diagnostics package, but should, for purposes of consistency, adhere
to the error log formats in <xref linkend="dbdoclet.50569337_42315"/>.</para>
to the error log formats in <xref linkend="LoPAR.Error"/>.</para>
</section>

<section xml:id="sec_platform_class">
<title>Platform Class</title>
<para>The <emphasis role="bold"><literal>&#x201C;ibm,model-class&#x201D;</literal></emphasis> OF property
is defined to classify platforms for planning, marketing, licensing, and
service purposes (see <xref linkend="dbdoclet.50569368_54493"/>).</para>
service purposes (see "Root Node Properties" in
<xref linkend="LoPAR.DeviceTree"/>).</para>

<variablelist>
<varlistentry>
@ -1711,7 +1696,7 @@ ELSE
<para> OR</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569342_75822"/> for more information. </para>
<para> See <xref linkend="LoPAR.Virtualization"/> for more information. </para>
</entry>
</row>
<row>
@ -1725,7 +1710,7 @@ ELSE
<para> OR</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569342_75053"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1741,8 +1726,8 @@ ELSE
<entry>
<para> See <xref linkend="dbdoclet.50569330_34831"/> and
<xref linkend="dbdoclet.50569330_17337"/>. Requirements for platforms that implement
LPAR, regardless of the number of partitions (Requirements <xref linkend="dbdoclet.50569344_47137"/>
and <xref linkend="dbdoclet.50569344_28369"/>).</para>
LPAR, regardless of the number of partitions, are contained in
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1770,7 +1755,7 @@ ELSE
<para> R</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569344_14591"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1816,7 +1801,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569332_19739"/> for more information on
<para> See <xref linkend="LoPAR.RTAS"/> for more information on
support of I<superscript>2</superscript>C buses.</para>
</entry>
</row>
@ -1831,7 +1816,7 @@ ELSE
<para> R</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569332_12478"/>. </para>
<para><xref linkend="LoPAR.RTAS"/>. </para>
</entry>
</row>
<row>
@ -1845,7 +1830,7 @@ ELSE
<para> R</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569332_24237"/>.</para>
<para><xref linkend="LoPAR.RTAS"/>.</para>
</entry>
</row>
<row>
@ -1859,7 +1844,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569332_41873"/>.</para>
<para><xref linkend="LoPAR.RTAS"/>.</para>
</entry>
</row>
<row>
@ -1873,7 +1858,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569332_61466"/>.</para>
<para><xref linkend="LoPAR.RTAS"/>.</para>
</entry>
</row>
<row>
@ -1903,7 +1888,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569344_27067"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1917,7 +1902,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569348_48491"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1931,7 +1916,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569348_61656"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1945,7 +1930,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569350_23147"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1959,7 +1944,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569350_17923"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1973,7 +1958,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569350_53238"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -1987,7 +1972,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569350_39278"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2001,7 +1986,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569351_35753"/>.</para>
<para><xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2015,7 +2000,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569364_64078"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2029,7 +2014,8 @@ ELSE
<para> NS</para>
</entry>
<entry>
<para><xref linkend="dbdoclet.50569327_70628"/> and <xref linkend="dbdoclet.50569332_28221"/>.</para>
<para><xref linkend="dbdoclet.50569327_70628"/> and "Managing
Storage Preservations" in <xref linkend="LoPAR.RTAS"/> specification.</para>
</entry>
</row>
<row>
@ -2046,7 +2032,7 @@ ELSE
<para> Required of all platforms that support LPAR, otherwise not
implemented. Provides a virtual &#x201C;Asynchronous&#x201D; IOA for connecting
to a server Vterm IOA, the hypervisor, or HMC (for example, to a virtual
console). See <xref linkend="dbdoclet.50569352_15379"/> for more
console). See <xref linkend="LoPAR.Virtualization"/> for more
information.</para>
</entry>
</row>
@ -2082,7 +2068,7 @@ ELSE
</row>
<row>
<entry>
<para>Performance Tool Support</para>
<para> Performance Tool Support</para>
</entry>
<entry>
<para> O</para>
@ -2092,9 +2078,8 @@ ELSE
</entry>
<entry>
<para> Provides access to platform-level facilities for
performance tools running in a partition on an LPAR system.
See
<xref linkend="dbdoclet.50569332_26596"/>.></para>
performance tools running in a partition on an LPAR system. See
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2122,7 +2107,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569350_39077"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2136,7 +2121,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="sec_vmc"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2231,7 +2216,7 @@ ELSE
<entry>
<para> Allows an authorized virtual server partition (VSP) to
safely access the internal state of a specific partition. See
<xref linkend="sec_vasi"/> for more details. Requires the Reliable
<xref linkend="LoPAR.Virtualization"/> for more details. Requires the Reliable
Command/Response Transport option.</para>
</entry>
</row>
@ -2263,7 +2248,7 @@ ELSE
<entry>
<para> Allows the OS to indicate that there is no need to search
secondary page table entry groups to determine a page table search has failed.
See <xref linkend="dbdoclet.50569344_39908"/> for more details.</para>
See <xref linkend="LoPAR.Virtualization"/> for more details.</para>
</entry>
</row>
<row>
@ -2307,7 +2292,7 @@ ELSE
</entry>
<entry>
<para> Support for the Subordinate CRQs as needed by some Virtual
IOAs. See <xref linkend="dbdoclet.50569348_28179"/>.</para>
IOAs. See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2323,7 +2308,7 @@ ELSE
<entry>
<para> The CMO option allows for partition participation in the
over-commitment of logical memory by the platform. See
<xref linkend="dbdoclet.50569344_44716"/>.</para>
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2338,7 +2323,7 @@ ELSE
</entry>
<entry>
<para> Allows the OS to cooperate with platform energy
management. See <xref linkend="dbdoclet.50569344_18587"/>.</para>
management. See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2353,7 +2338,7 @@ ELSE
</entry>
<entry>
<para> Support for the Multi-TCE-Table Option. See
<xref linkend="dbdoclet.50569344_50921"/>.</para>
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2369,7 +2354,7 @@ ELSE
<entry>
<para> Provides substantially consistent virtual processor
associativity in a shared processor LPAR environment. See
<xref linkend="dbdoclet.50569344_56450"/>.</para>
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2397,7 +2382,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569366_19541"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2412,7 +2397,7 @@ ELSE
</entry>
<entry>
<para> Allows OS notification of a cooperative memory
overcommitment page fault see <xref linkend="dbdoclet.50569344_20827"/>.</para>
overcommitment page fault see <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2428,7 +2413,7 @@ ELSE
<entry>
<para> Allows the platform to communicate and the availability of
performance boost modes along with any ability to manage the same. See
<xref linkend="dbdoclet.50569332_57301"/></para>
<xref linkend="LoPAR.RTAS"/></para>
</entry>
</row>
<row>
@ -2460,7 +2445,7 @@ ELSE
</entry>
<entry>
<para> Allows the creation of DMA Windows above 4 GB. See
<xref linkend="dbdoclet.50569332_14137"/>.</para>
<xref linkend="LoPAR.RTAS"/>.</para>
</entry>
</row>
<row>
@ -2475,7 +2460,7 @@ ELSE
</entry>
<entry>
<para>
<xref linkend="dbdoclet.50569368_54493"/> for information on ibm,partition-uuid.
<xref linkend="LoPAR.DeviceTree"/> for information on ibm,partition-uuid.
</para>
</entry>
</row>
@ -2490,9 +2475,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="dbdoclet.50569344_80550"/>,
<xref linkend="dbdoclet.50569344_61580"/>, and
<xref linkend="dbdoclet.50569344_93738"/> for more information.</para>
<para> See <xref linkend="LoPAR.Virtualization"/> for more information.</para>
</entry>
</row>
<row>
@ -2507,7 +2490,7 @@ ELSE
</entry>
<entry>
<para> Introduces additional cooperative memory overcommitment
functions see <xref linkend="dbdoclet.50569344_44716"/></para>
functions see <xref linkend="LoPAR.Virtualization"/></para>
</entry>
</row>
<row>
@ -2521,7 +2504,7 @@ ELSE
<para> O</para>
</entry>
<entry>
<para> See <xref linkend="sec_mui_opt"/>.</para>
<para> See <xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2580,7 +2563,7 @@ ELSE
</entry>
<entry>
<para>Allows partitions to resize their HPT. See
<xref linkend="sec_hash_page_table_resize_option"/>.</para>
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
<row>
@ -2594,8 +2577,8 @@ ELSE
<para>O</para>
</entry>
<entry>
<para>See
<xref linkend="sec_coherent_platform_facilities"/>.</para>
<para>Allows partitions to resize their HPT. See
<xref linkend="LoPAR.Virtualization"/>.</para>
</entry>
</row>
</tbody>

0
LoPAR/figures/PAPR-10.gif → Platform/figures/PAPR-10.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 66 KiB

After

Width:  |  Height:  |  Size: 66 KiB

0
LoPAR/figures/PAPR-11.gif → Platform/figures/PAPR-11.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 133 KiB

After

Width:  |  Height:  |  Size: 133 KiB

0
LoPAR/figures/PAPR-12.gif → Platform/figures/PAPR-12.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 65 KiB

0
LoPAR/figures/PAPR-14.gif → Platform/figures/PAPR-14.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 64 KiB

0
LoPAR/figures/PAPR-15.gif → Platform/figures/PAPR-15.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
LoPAR/figures/PAPR-3.gif → Platform/figures/PAPR-3.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

0
LoPAR/figures/PAPR-32.gif → Platform/figures/PAPR-32.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

0
LoPAR/figures/PAPR-4.gif → Platform/figures/PAPR-4.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

0
LoPAR/figures/PAPR-6.gif → Platform/figures/PAPR-6.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

0
LoPAR/figures/PAPR-7.gif → Platform/figures/PAPR-7.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

0
LoPAR/figures/PAPR-8.gif → Platform/figures/PAPR-8.gif
Unescape Escape View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 56 KiB

47
LoPAR/pom.xml → Platform/pom.xml
Unescape Escape View File

@ -1,23 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>

<groupId>org.openpowerfoundation.docs</groupId>
@ -31,9 +15,9 @@
<artifactId>LoPAR-Platform</artifactId>

<packaging>jar</packaging>

<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>LoPAR</name>
<name>LoPAR-Platform</name>

<properties>
<!-- This is set by Jenkins according to the branch. -->
@ -72,8 +56,8 @@
book/appendix nop
book/chapter nop
chapter toc,title
chapter/section nop
section nop
chapter/section nop
section toc
part toc,title
qandadiv toc
qandaset toc
@ -82,19 +66,19 @@
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>1</sectionAutolabel>
<tocSectionDepth>10</tocSectionDepth>
<tocSectionDepth>3</tocSectionDepth>
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>

<!-- TODO: Rename the webhelpDirname field to the new directory for new document -->
<webhelpDirname>LoPAR</webhelpDirname>
<webhelpDirname>LoPAR_Platform</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>LoPAR</pdfFilenameBase>
<pdfFilenameBase>LoPAR_Platform</pdfFilenameBase>

<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
Consult with the Work Group Chair or a Technical Steering Committee member if you have
questions about which value to select.

If no value is provided below, the document will default to "Work Group Notes".-->
<workProduct>workgroupNotes</workProduct>
<!-- workProduct>workgroupSpecification</workProduct -->
@ -118,13 +102,13 @@
other Foundation members or the public

The appropriate starting security for a new document is "workgroupConfidential". -->
<security>public</security>
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->

<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and create a vertical running ribbon on the internal margin of the
and create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

@ -136,8 +120,8 @@

The appropriate starting security for a new document is "draft". -->
<!-- documentStatus>draft</documentStatus -->
<documentStatus>published</documentStatus>
<!-- documentStatus>publish</documentStatus -->
<documentStatus>review</documentStatus>
<!-- documentStatus>publish</documentStatus -->

</configuration>
</execution>
@ -161,3 +145,4 @@
</plugins>
</build>
</project>

6
README.md
Unescape Escape View File

@ -53,8 +53,10 @@ Document library at [TBD](http://openpowerfoundation.org/?resource_lib=tbd)


## Contributions
Contributions to this project should be done in the fork/pull-request model,
and also conform to the `Developer Certificate
To contribute to the OpenPOWER Foundation template document project, contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or
Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\).

Contributions to this project should conform to the `Developer Certificate
of Origin` as defined at http://elinux.org/Developer_Certificate_Of_Origin.
Commits to this project need to contain the following line to indicate
the submitter accepts the DCO:

284
RTAS/app_bibliography.xml
Unescape Escape View File

@ -0,0 +1,284 @@
<?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:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dbdoclet.50569387_27251">
<?dbhtml stop-chunking?>
<title> Bibliography</title>
<para>This section lists documents which were referenced in this specification or which provide
additional information, and some useful information for obtaining these documents. Referenced
documents are listed below. When any of the following standards are superseded by an approved
revision, the revision shall apply.</para>
<orderedlist>
<!-- TODO: Uncomment documents needing referencing and comment out local document -->
<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>
<para><anchor xml:id="LoPAR.DeviceTree"
xreflabel="Linux on Power Architecture Reference: Device Tree"/><citetitle>
Linux on Power Architecture Reference: Device Tree</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.Error"
xreflabel="Linux on Power Architecture Reference: Error Recovery and Logging"/><citetitle>
Linux on Power Architecture Reference: Error Recovery and Logging</citetitle></para>
</listitem>

<listitem>
<para><anchor xml:id="LoPAR.Virtualization"
xreflabel="Linux on Power Architecture Reference: Virtualization"/><citetitle>
Linux on Power Architecture Reference: Virtualization</citetitle></para>
</listitem>

<!-- listitem>
<para><anchor xml:id="LoPAR.RTAS"
xreflabel="Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)"/><citetitle>
Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS)</citetitle></para>
</listitem -->
<!-- End TODO list -->

<listitem>
<para><citetitle>Power ISA</citetitle><anchor xml:id="dbdoclet.50569387_99718"
xreflabel="Power ISA specification"/></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_45524"
xreflabel="IEEE Open Firmware standard"/>
<citetitle>IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware:
Core Requirements and Practices</citetitle></para>
<para>IEEE part number DS02683, ISBN 1-55937-426-8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_14175"
xreflabel="IEEE Open Firmware Errata specification"/>
<citetitle>Core Errata, IEEE P1275.7/D4</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_31707"
xreflabel="Open Firmware TFTP extensions"/>
<citetitle>Open Firmware Recommended Practice:OBP-TFTP
Extension</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27008"
xreflabel="Open Firmware Device Support Extensions specification"/>
<citetitle>Open Firmware Recommended Practice: Device
Support Extensions</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22451"
xreflabel="PCI Bus Binding to Open Firmware standard"/>
<citetitle>PCI Bus binding to: IEEE Std 1275-1994, Standard
for Boot (Initialization, Configuration) Firmware</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_40740"
xreflabel="Open Firmware Interrupt Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33384"
xreflabel="Open Firmware Forth Source and FCode Image Support specification"/>
<citetitle>Open Firmware: Recommended Practice - Forth Source
and FCode Image Support</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_67880"
xreflabel="Open Firmware Interrup Mapping specification"/>
<citetitle>Open Firmware: Recommended Practice - Interrupt
Mapping</citetitle>, Version 1.0</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_33177"
xreflabel="Open Firmware TFTP Booting extensions"/>
<citetitle>Open Firmware: Recommended Practice - TFTP Booting
Extensions</citetitle>, Version 0.8</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_27351"
xreflabel="Open Firmware Interposition specification"/>
<citetitle>Open Firmware: Recommended Practice -
Interposition</citetitle>, Version 0.2</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_22601"
xreflabel="MS-DOS Programmer's Reference specification"/>
<citetitle>MS-DOS Programmer's Reference</citetitle></para>
<para>Published by Microsoft</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_18190"
xreflabel="Win32 Executable File Format article"/>
<citetitle>Peering Inside the PE: A Tour of the Win32 Portable
Executable File Format</citetitle></para>
<para>Found in the March, 1994 issue of <citetitle> Microsoft Systems Journal</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_85757"
xreflabel="CD-ROM Volume and File Structure standard"/>
<citetitle> ISO-9660, Information processing -- Volume and
file structure of CD-ROM for information interchange</citetitle></para>
<para>Published by International Organization for Standardization</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38836"
xreflabel="System V Application Binary Interface, PowerPC Processor supplement"/>
<citetitle>System V Application Binary Interface, PowerPC
Processor Supplement</citetitle></para>
<para>By Sunsoft<citetitle></citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_11453"
xreflabel="Standard Generalized Markup Language (SGML) standard"/>
<citetitle>ISO Standard 8879:1986, Information Processing
-- Text and Office Systems -- Standard Generalized Markup Language (SGML)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_38891"
xreflabel="Personal Computer Back Plane Bus standard"/>
<citetitle>IEEE 996, A Standard for an Extended Personal Computer
Back Plane Bus</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_65468"
xreflabel="PCI Local Bus specification"/>
<citetitle>PCI Local Bus Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_60429"
xreflabel="PCI-to-PCI Bridge Architecture specification"/>
<citetitle>PCI-to-PCI Bridge Architecture Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design conventional PCI related components or platforms. See the
PCI SIG website for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_87046"
xreflabel="PCI Standard Hot-Plug Controller and Subsystem specification"/>
<citetitle>PCI Standard Hot-Plug Controller and Subsystem
Specification</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_26550"
xreflabel="PCI-X Protocol addendum"/>
<citetitle>PCI-X Protocol Addendum to the PCI Local Bus Specification </citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI-X related components or platforms. See the PCI SIG website for the most
current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_66784"
xreflabel="PCI Express Base specification"/>
<citetitle>PCI Express Base Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document
at the time that they design PCI Express related components or platforms. See the PCI SIG website for
the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_28381"
xreflabel="PCI Express to PCI/PCI-X Bridge specification"/>
<citetitle>PCI Express to PCI/PCI-X Bridge Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express related components or platforms. See the PCI SIG website for the most current
version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_34114"
xreflabel="System Management BIOS reference"/>
<citetitle>System Management BIOS (SMBIOS) Reference
Specification</citetitle></para>
</listitem>
<!-- TODO: Are the following 3 items needed? -->
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><!-- anchor xml:id="dbdoclet.50569387_72648" xreflabel=""/ --><citetitle>(List Number Reserved for Compatibility)</citetitle></para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_16481"
xreflabel="RS/6000 Product Topology Data System and Product Development guide"/>
<citetitle>IBM RS/6000&#174; Division, Product Topology Data System,
Product Development Guide</citetitle></para>
<para>Version 2.1</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_94229"
xreflabel="Single Root I/O Virtualization and Sharing specification"/>
<citetitle>Single Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at
the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website
for the most current version of this document.</para>
</listitem>
<listitem>
<para><anchor xml:id="dbdoclet.50569387_42471"
xreflabel="Multi-Root I/O Virtualization and Sharing specification"/>
<citetitle>Multi-Root I/O Virtualization and Sharing Specification</citetitle></para>
<para>All designers are responsible for assuring that they use the most current version of this document at the
time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the
most current version of this document.</para>
</listitem>
</orderedlist>

</appendix>

1290
RTAS/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

347
RTAS/bk_main.xml
Unescape Escape View File

@ -0,0 +1,347 @@
<?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"
status="draft"
xml:id="bk_main">

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

<title>Runtime Abstraction Services</title>
<subtitle>Linux on Power Architecture Reference</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_pre5</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 Runtime Abstraction Services (firmware) on 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="http://tbd.openpowerfoundation.org">TBD</link>.</para>
</abstract>

<revhistory>
<!-- TODO: Update as new revisions created -->
<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 7 (Run-time Abstration Services), Appendix G (Firmware Assisted
Dump Data Format), and Appendix I (CMO Characteristics Definition).</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="../common/ch_LoPAR_preface.xml"/>

<!-- Chapter heading files -->
<xi:include href="ch_rtas_introduction.xml"/>
<xi:include href="ch_rtas_environment.xml"/>
<xi:include href="ch_rtas_call_defn.xml"/>
<xi:include href="ch_firmware_dump.xml"/>
<xi:include href="ch_cmo_def.xml"/>


<!-- Document specific appendices -->
<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="../common/app_EOD.xml"/>

</book>

50
LoPAR/app_cmo_def.xml → RTAS/ch_cmo_def.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,40 +13,40 @@
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"
<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"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569382_58396">

<title>CMO Characteristics Definitions</title>

<para>This appendix defines the string that is returned by the
<para>This chapter 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
token value of 44 (CMO Characteristics) is specified on the
<emphasis>ibm,get-system-parameter</emphasis> RTAS call as per
<xref linkend="dbdoclet.50569332_62190"/>.</para>

<section>
<title>CMO Terms</title>
<para>The LoPAR Cooperative Memory Over-commitment option (CMO) defines
terms as presented in
terms as presented in
<xref linkend="dbdoclet.50569382_93865" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569382_93865">
<title>CMO Terms</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<tbody valign="middle" >
<colspec colname="c1" colwidth="50*" />
<colspec colname="c2" colwidth="50*" />
<tbody>
<row>
<entry>
<para>Term</para>
</entry>
<entry align="center">
<entry>
<para>Definition</para>
</entry>
</row>
@ -89,14 +89,14 @@
</tgroup>
</table>
</section>

<section>
<title>Key Words And Values</title>
<para>
<xref linkend="dbdoclet.50569382_70763" />defines the key words and the
associated legal values that will be returned in the ASCII NULL terminated
string when the parameter token value of 44 (CMO characteristics) is
specified on the
specified on the
<emphasis>ibm,get-system-parameter</emphasis> RTAS call. The key word and
value is separated by an ASCII equal (&#8220;=&#8221;). Each key word,
value pair is delimited by an ASCII comma in the string. The numerical
@ -107,11 +107,11 @@
<table frame="all" pgwide="1" xml:id="dbdoclet.50569382_70763">
<title>CMO Characteristics</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>Characteristics</para>
@ -122,7 +122,7 @@
<entry>
<para>Values</para>
</entry>
<entry align="center">
<entry>
<para>Notes</para>
</entry>
</row>
@ -170,4 +170,4 @@
</tgroup>
</table>
</section>
</appendix>
</chapter>

1272
RTAS/ch_error_codes.xml
View File

File diff suppressed because it is too large Load Diff

130
LoPAR/app_firmware_dump.xml → RTAS/ch_firmware_dump.xml
Unescape Escape View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation

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
@ -13,26 +13,26 @@
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"
<chapter 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
Configure Platform Assisted Kernel Dump option
()<xref linkend="dbdoclet.50569332_67111" />).</para>

<para>This Appendix documents the dump data format, in support of the
Configure Platform Assisted Kernel Dump option in
<xref linkend="LoPAR.Virtualization" />.</para>
<section xml:id="dbdoclet.50569380__Ref135446652">
<title>Register Save Area</title>
<para>The register save area is an area in the partition&#8217;s memory
used to preserve the registers for the active CPUs during a firmware
assisted dump. The location and size of this area is specified by the
partition when firmware assisted dumpwhen it registers for firmware
assisted dump using the <xref linkend="dbdoclet.50569332_67111" />.
assisted dump using the <xref linkend="dbdoclet.50569332_67111" />.
The minimum size will be sent to the
partition in the PFDS KDUMP node.</para>
<para>The register save is a semi-free format list of registers for each
@ -43,8 +43,8 @@
<para>
<emphasis role="bold">Notes:</emphasis>
</para>

<orderedlist>
<orderedlist>
<listitem>
<para>Only CPUs that are online at the start of the Firmware Assisted
Dump will have their register data saved.</para>
@ -59,24 +59,24 @@
required to be in any specific order (To make debug easier they will most
likely be placed in ascending ASCII identifier order)</para>
</listitem>

<listitem>
<para>If the CPU is in a Transactional Memory operating mode such
that there is a valid register check point, the contents of that register
checkpoint is included with register identifiers starting with “X-”, see
<para>If the CPU is in a Transactional Memory operating mode such
that there is a valid register check point, the contents of that register
checkpoint is included with register identifiers starting with “X-”, see
<xref linkend="table_identifiers_supported" />,
else the checkpoint registers are not included.</para>
</listitem>
</orderedlist>

</orderedlist>
<table frame="all" pgwide="1">
<title>Register Save Area Format</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="23*" align="center" />
<colspec colname="c4" colwidth="23*" />
<colspec colname="c5" colwidth="23*" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<thead>
<row>
<entry>
@ -94,19 +94,19 @@
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<tbody>
<row>
<entry>
<para>0x00</para>
@ -301,11 +301,11 @@
<table frame="all" pgwide="1">
<title>RegEntry Format</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="23*" align="center" />
<colspec colname="c4" colwidth="23*" align="center" />
<colspec colname="c5" colwidth="23*" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<thead>
<row>
<entry>
@ -328,14 +328,14 @@
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x0</para>
@ -377,10 +377,10 @@
<table frame="all" pgwide="1">
<title>CPUSTRT and CPUEND have the following format</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<tbody valign="middle" >
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<tbody>
<row>
<entry>
<para>8 Byte Identifier</para>
@ -399,9 +399,9 @@
<table frame="all" pgwide="1">
<title>8-Byte RegEntries</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<tbody valign="middle" >
<colspec colname="c1" colwidth="50*" />
<colspec colname="c2" colwidth="50*" />
<tbody>
<row>
<entry>
<para>8 Byte Identifier</para>
@ -417,10 +417,10 @@
<table frame="all" pgwide="1">
<title>4-Byte RegEntries</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<tbody valign="middle" >
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<tbody>
<row>
<entry>
<para>8 Byte Identifier</para>
@ -440,8 +440,8 @@
<title>Identifiers Supported in Version 0x0 of the
Table</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
@ -455,14 +455,14 @@
<emphasis role="bold">Identifier (ASCII)</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x4350555354525400</para>
@ -6004,11 +6004,11 @@
<table frame="all" pgwide="1">
<title>HPT Entry Save Area Format</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="23*" align="center" />
<colspec colname="c4" colwidth="23*" align="center" />
<colspec colname="c5" colwidth="23*" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<thead>
<row>
<entry>
@ -6031,14 +6031,14 @@
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x00</para>
@ -6184,11 +6184,11 @@
<table frame="all" pgwide="1">
<title>HPT Entry Format</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="23*" align="center" />
<colspec colname="c4" colwidth="23*" align="center" />
<colspec colname="c5" colwidth="23*" />
<colspec colname="c1" colwidth="20*" />
<colspec colname="c2" colwidth="20*" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" />
<colspec colname="c5" colwidth="20*" />
<thead>
<row>
<entry>
@ -6211,14 +6211,14 @@
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<tbody>
<row>
<entry>
<para>0x0</para>
@ -6278,5 +6278,5 @@
is up to the user of the save area to sort the data.</para>
<para />
</section>

</appendix>
</chapter>

1078
LoPAR/sec_rtas_call_defn.xml → RTAS/ch_rtas_call_defn.xml
View File

File diff suppressed because it is too large Load Diff

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

Write Preview
Loading…
Cancel
Save