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

Initial repo priming from IBM Internal tree.

Browse Source 
Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
pull/2/head
Jeff Scheel 7 years ago
commit ab490e8ff0
135 changed files with 143708 additions and 0 deletions
Show Stats Download Patch File Download Diff File

2
.gitignore vendored
Unescape Escape View File

@ -0,0 +1,2 @@
*~
*target*

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

109
DeviceTree/bk_main.xml
Unescape Escape View File

@ -0,0 +1,109 @@
<?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</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.0_pre1</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. It 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>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>

4376
DeviceTree/ch_devtree_pa.xml
View File

File diff suppressed because it is too large Load Diff

10452
DeviceTree/ch_devtree_system.xml
View File

File diff suppressed because it is too large Load Diff

330
DeviceTree/ch_devtree_terms.xml
Unescape Escape View File

@ -0,0 +1,330 @@
<?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_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>
<listitem>
<para>Address Resolution Protocol</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">BOOTP</emphasis></term>
<listitem>
<para>Bootstrap Protocol</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">CHRP</emphasis></term>
<listitem>
<para>Common Hardware Reference Platform</para>
</listitem>
</varlistentry>

<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">CPU</emphasis></term>
<listitem>
<para>Central Processing Unit</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">ELF Executable and Linking Format</emphasis></term>
<listitem>
<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>
</varlistentry>

<varlistentry>
<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
<xref linkend="dbdoclet.50569387_22601" />.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">gateway</emphasis></term>
<listitem>
<para>Network connecting device</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">host</emphasis></term>
<listitem>
<para>A computer. In particular a source or destination of messages
from the point of view of the communication network.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">ICMP</emphasis></term>
<listitem>
<para>Internet Control Message Protocol</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">IETF</emphasis></term>
<listitem>
<para>Internet Engineering Task Force</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">IP</emphasis></term>
<listitem>
<para>Internet Protocol</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">IO</emphasis></term>
<listitem>
<para>Input/Output</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">LAN</emphasis></term>
<listitem>
<para>Local Area Network</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">NVRAM</emphasis></term>
<listitem>
<para>Non-volatile memory that is the repository for various
platform, OF and OS information that remains persistent across reboots,
power management activities and/or cycles.</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">PCU</emphasis></term>
<listitem>
<para>Power Configuration Utility; Refers to a platform program to
assist a user to manage device power.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">PE</emphasis></term>
<listitem>
<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>
<para>Programmable Read Only Memory</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">RFC</emphasis></term>
<listitem>
<para>Internet Request For Comments; part of the technical process of
establishing a standard.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">ROM</emphasis></term>
<listitem>
<para>Read Only Memory</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">TFTP</emphasis></term>
<listitem>
<para>Trivial File Transfer Protocol</para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">UDP</emphasis></term>
<listitem>
<para>User Datagram Protocol</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>
</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>

BIN
DeviceTree/figures/PAPR-60.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
DeviceTree/figures/PAPR-61.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

BIN
DeviceTree/figures/PAPR-62.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
DeviceTree/figures/PAPR-64.gif
View File

Binary file not shown.
Side by Side

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>

891
Error Handling/app_fault_v_errorlog.xml
Unescape Escape View File

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

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569385_36278">
<title>
When to use: Fault vs. Error Log Indicators (Lightpath Mode)</title>
<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
answer common questions about how to handle specific issues. The reason that
these are recommended rather than required, is due to the range of systems
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
<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
<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="LoPAR.Platform" />:</para>
<informalfigure>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-73.gif" format="GIF" scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-73.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</informalfigure>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569385_72358">
<title>Service Indicator Activation Models for Typical System
Issues (Lightpath Mode)
<emphasis></emphasis></title>
<tgroup cols="7">
<colspec colname="c1" colwidth="15*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="14*" align="center" />
<colspec colname="c4" colwidth="10*" align="center" />
<colspec colname="c5" colwidth="8*" align="center" />
<colspec colname="c6" colwidth="8*" align="center" />
<colspec colname="c7" colwidth="20*" />
<thead>
<row>
<entry morerows="1" align="center" valign="middle">
<para>
<emphasis role="bold">Component or problem area</emphasis>
</para>
</entry>
<entry morerows="1" align="center" valign="middle">
<para>
<emphasis role="bold">Problem or issue</emphasis>
</para>
</entry>
<entry nameend="c4" namest="c3">
<para>
<emphasis role="bold">Indicator activation?
<emphasis><?linebreak?>(see notes
<xref linkend="dbdoclet.50569385_14395" xrefstyle="select: nopage" />,
<xref linkend="dbdoclet.50569385_43948" xrefstyle="select: nopage" />)</emphasis></emphasis>
</para>
</entry>
<entry morerows="1" valign="middle">
<para>
<emphasis role="bold">Entry made in Service Focal Point error
log?</emphasis>
</para>
</entry>
<entry morerows="1" valign="middle">
<para>
<emphasis role="bold">IBM Call Home?</emphasis>
</para>
</entry>
<entry morerows="1" align="center" valign="middle">
<para>
<emphasis role="bold">Comments</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>FRU Fault indicator?<?linebreak?>(see notes
<xref linkend="dbdoclet.50569385_57037" xrefstyle="select: nopage" />,
<xref linkend="dbdoclet.50569385_69283" xrefstyle="select: nopage" />)</para>
</entry>
<entry>
<para>Error Log indicator?<?linebreak?>(see note
<xref linkend="dbdoclet.50569385_69283" xrefstyle="select: nopage" />)</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>All</para>
</entry>
<entry>
<para>Any not already covered in this table</para>
</entry>
<entry nameend="c6" namest="c3">
<para>Consult with the xipSIA architecture team for the proper
behavior</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>Power supply or fan</para>
</entry>
<entry>
<para>Redundant optional one missing</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>This row for information only (this is not a Serviceable
Event).</para>
</entry>
</row>
<row>
<entry>
<para>Redundant non-optional one missing</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Failed redundant</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Failed non-redundant</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Power regulator not in power supply</para>
</entry>
<entry>
<para>Failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>Treated the same as any other FRU or component on a FRU which
fails.</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Power</para>
</entry>
<entry>
<para>Insufficient power with all power supplies installed and
operational for power domain</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry morerows="1">
<para>For components that will not power up due to lack of power
(for example, a blade in a chassis), and when that component
implements a fast blink capability for the green power LED, that
component&#8217;s green power LED remains in the fast blink
mode.</para>
</entry>
</row>
<row>
<entry>
<para>Insufficient power with missing power supply</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Disabled button pressed</para>
</entry>
<entry>
<para>Unable to power on or off component due to power button being
disabled</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry morerows="1">
<para>These rows for information only (these are not a Serviceable
Events).</para>
</entry>
</row>
<row>
<entry>
<para>KVM or media tray button pressed, but not active because
disabled</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Temperature detected out of tolerance</para>
</entry>
<entry>
<para>Warning only (no performance throttling or shut-down)</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>brand dependent</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Performance throttling or shut-down due to over-temp
condition</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>FRU Fault indicator must be at component that is throttled or
shut-down (temperature indicators, which are not architected, do
not roll-up to Enclosure Fault indicators).</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>Memory (DIMMs)</para>
</entry>
<entry>
<para>No memory installed at all, or memory that is installed is
mismatched</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Invalid memory configuration above the base memory (missing
memory, mismatched memory, unsupported memory)</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Failed or predicted to fail</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>System VPD</para>
</entry>
<entry>
<para>Invalid or missing</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>Lack of some of the required fields in the call-home may
result in the call-home being flagged as a lack of
entitlement.</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Battery</para>
</entry>
<entry>
<para>Missing or failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>brand dependent</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Rechargeable battery needing reconditioning</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>CPU</para>
</entry>
<entry>
<para>Failed or predicted to fail</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Planar or CEC</para>
</entry>
<entry>
<para>Failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Disk</para>
</entry>
<entry>
<para>Failed or predicted to fail</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Boot device</para>
</entry>
<entry>
<para>Missing boot device</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Corrupt image</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>I/O adapter</para>
</entry>
<entry>
<para>Fail or non-recoverable EEH error</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Service Processor (FSP, BMC, IMM)</para>
</entry>
<entry>
<para>Hardware failure</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Firmware failure</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>brand dependent</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>BIOS or Flash</para>
</entry>
<entry>
<para>Corrupted single side</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Both sides corrupted</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>All</para>
</entry>
<entry>
<para>Unisolated event</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>See also Requirement
<xref linkend="dbdoclet.50569347_86824" /></para>
</entry>
</row>
<row>
<entry>
<para>Switch</para>
</entry>
<entry>
<para>Failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>System chassis controller (AMM, CME, ITME)</para>
</entry>
<entry>
<para>Failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Midplane</para>
</entry>
<entry>
<para>Failed</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Cables</para>
</entry>
<entry>
<para>Failed or missing</para>
</entry>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold">Notes:</emphasis>
</para>
<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
<xref linkend="dbdoclet.50569385_72358" />.</para>
</listitem>

<listitem xml:id="dbdoclet.50569385_43948">
<para>Fault indicators
above the FRU Fault indicator are not specified here, but the requirements
specify that a FRU Fault is rolled-up to the next higher level indicator
(specifically, the Enclosure Fault indicator).</para>
</listitem>

<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
<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
<xref linkend="dbdoclet.50569385_72358" />).</para>
</listitem>

<listitem xml:id="dbdoclet.50569385_69283">
<para>The activation of the
Error Log indicator (previously known as the System Information (Attention)
indicator) and Fault indicators are regulated by the following requirements,
among others:</para>
<itemizedlist>
<listitem><para><xref linkend="dbdoclet.50569347_17215"/></para></listitem>
<listitem><para><xref linkend="dbdoclet.50569347_38463"/></para></listitem>
</itemizedlist>
</listitem>
</orderedlist>

</appendix>

1290
Error Handling/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

111
Error Handling/bk_main.xml
Unescape Escape View File

@ -0,0 +1,111 @@
<?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</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.0_pre1</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. It 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>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"/>
<xi:include href="ch_service_indicators.xml"/>

<!-- Document specific appendices -->
<xi:include href="app_fault_v_errorlog.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>

1280
Error Handling/ch_error_codes.xml
View File

File diff suppressed because it is too large Load Diff

30
Error Handling/ch_notifications.xml
Unescape Escape View File

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

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
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_error_reporting.xml"/>
</chapter>

321
Error Handling/ch_rtas_error_classes.xml
Unescape Escape View File

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

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
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
<emphasis>event-scan</emphasis> RTAS functions. More detailed descriptions
of these classes are given later in this chapter.
<xref linkend="dbdoclet.50569337_82470"/> defines nodes in the OF device
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
<emphasis>check-exception</emphasis>. The OF structure for describing these
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*" />
<colspec colname="c2" colwidth="40*" />
<colspec colname="c3" colwidth="20*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Class Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">OF Node Name(where the
<literal>&#8220;interrupts&#8221;</literal> property lists the
interrupts)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">RTAS Function Call Mask(value = 1 enables
class)</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Internal Errors</para>
</entry>
<entry>
<para>internal-errors</para>
</entry>
<entry>
<para>bit 0</para>
</entry>
</row>
<row>
<entry>
<para>Environmental and Power Warnings</para>
</entry>
<entry>
<para>epow-events</para>
</entry>
<entry>
<para>bit 1</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>bit 2</para>
</entry>
</row>
<row>
<entry>
<para>Hot Plug Events</para>
</entry>
<entry>
<para>hot-plug-events</para>
</entry>
<entry>
<para>bit 3</para>
</entry>
</row>
<row>
<entry>
<para>I/O Events and Errors</para>
</entry>
<entry>
<para>ibm,io-events</para>
</entry>
<entry>
<para>bit 4</para>
</entry>
</row>
</tbody>
</tgroup>
</table>

<variablelist>
<varlistentry>
<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
<emphasis role="bold"><literal>ibm,io-events</literal></emphasis> node property to specify the
interrupts.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<literal>&#8220;interrupts&#8221;</literal> property of the appropriate OF
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"
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
<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"
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
<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"
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
<emphasis>check-exception</emphasis> functions, using the reporting format
described in
<xref linkend="dbdoclet.50569337_21249"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<emphasis>check-exception</emphasis> functions, must be in the reporting
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"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>To provide control
over performance, the RTAS event reporting functions must not perform any
event data gathering for classes not selected in the event class mask
parameter, nor any extended data gathering if the time critical parameter
is non-zero or the log buffer length parameter does not allow for an
extended error log.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
notifications, the RTAS event reporting functions must be written to gather
and process error and event data without destroying the state information
of events other than the one being processed.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
error and event notification must not be shared between error and event
classes, or with any other types of interrupt mechanisms. This allows the
OS to partition its interrupt handling and prevents blocking of one class
of interrupt by the processing of another.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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
<xref linkend="dbdoclet.50569337_31164"/>, although the fixed-part return format
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
<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
<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
<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
was fatal at the time the failure occurred. The Severity field informs the
OS of the severity of the event at the time of reporting. Errors which
occurred before a successful reboot are no longer critical. Likewise, the
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
<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
<emphasis>RI</emphasis> bit is not set to 1. It is up to the OS to examine
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>

36
Error Handling/ch_rtas_error_reporting.xml
Unescape Escape View File

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

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en"
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
orientation. Bits are numbered from left (high-order:0) to right
(low-order:7).</para>

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

4168
Error Handling/ch_service_indicators.xml
View File

File diff suppressed because it is too large Load Diff

BIN
Error Handling/figures/PAPR-34.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
Error Handling/figures/PAPR-36.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
Error Handling/figures/PAPR-37.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
Error Handling/figures/PAPR-38.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
Error Handling/figures/PAPR-39.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1012 B

BIN
Error Handling/figures/PAPR-40.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
Error Handling/figures/PAPR-41.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
Error Handling/figures/PAPR-42.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Error Handling/figures/PAPR-43.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
Error Handling/figures/PAPR-44.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
Error Handling/figures/PAPR-45.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
Error Handling/figures/PAPR-46.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Error Handling/figures/PAPR-47.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Error Handling/figures/PAPR-48.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
Error Handling/figures/PAPR-49.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Error Handling/figures/PAPR-50.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
Error Handling/figures/PAPR-51.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.8 KiB

BIN
Error Handling/figures/PAPR-52.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Error Handling/figures/PAPR-53.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Error Handling/figures/PAPR-54.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.7 KiB

BIN
Error Handling/figures/PAPR-73.gif
View File

Binary file not shown.
Side by Side

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>

85
Error Handling/sec_error_introduction.xml
Unescape Escape View File

@ -0,0 +1,85 @@
<?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.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
hardware errors which have occurred as well as information about non-error
events, such as environmental conditions (for example, temperature or
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,
<emphasis>rtas-last-error</emphasis>, is also provided to return
information about hardware failures detected specifically within an RTAS
call.</para>
<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
<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
<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
behalf of the OS. The reporting format, described in this chapter, permits
firmware to report the type of error which has occurred, what entities in
the platform were involved in the error, and whether firmware has
successfully recovered from the error without the need for further OS
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
<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
determine the cause of a problem and report what it finds, to aid the end
user (by providing meaningful diagnostic data for messages) and to prevent
the loss of error syndrome information. Firmware is never required to
correct any problem, but in some cases may attempt to do so. System vendors
who want more extensive error diagnosis may create OS error handlers which
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>

336
Error Handling/sec_rtas_env_epow.xml
Unescape Escape View File

@ -0,0 +1,336 @@
<?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.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
environmental and power problems and to minimize the logical damage done
by these problems. For example, an OS might want to abort all disk I/O
operations in progress to ensure that disk sectors are not corrupted by
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
<emphasis>epow-events</emphasis> node in the OF device tree, enable the
interrupts listed in its
<literal>&#8220;interrupts&#8221;</literal> property, and provide an
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
<emphasis>event-scan</emphasis>, RTAS will directly pass back the EPOW
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
<emphasis>check-exception</emphasis> function is used to immediately
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"
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
<emphasis>get-sensor-state</emphasis> RTAS function.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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
<xref linkend="dbdoclet.50569337_45557"/> for those it does implement.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>If the platform
does not notify EPOW_MAIN_ENCLOSURE or EPOW_POWER_OFF via interrupt, then
the platform must protect data on I/O storage devices from corruption due
to the EPOW event.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
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
<emphasis role="bold"><literal>&#8220;ibm,recoverable-epow3&#8221;</literal></emphasis>
encode-null
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
<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>
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
<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*" />
<colspec colname="c2" colwidth="10*" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Action Code</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>EPOW_RESET/MESSAGE</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>No EPOW event is pending. This action code is the lowest
priority.</para>
</entry>
</row>
<row>
<entry>
<para>WARN_COOLING</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>A non-critical cooling problem exists. An EPOW-aware OS
logs the EPOW information.</para>
</entry>
</row>
<row>
<entry>
<para>WARN_POWER</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>A non-critical power problem exists. An EPOW-aware OS
logs the EPOW information.</para>
</entry>
</row>
<row>
<entry>
<para>SYSTEM_SHUTDOWN</para>
</entry>
<entry>
<para>3</para>
</entry>
<entry>
<para>The system must be shut down. An EPOW-aware OS logs the
EPOW error log information, then schedules the system to be
shut down to begin after an OS defined delay internal (default
is 10 minutes.)</para>
</entry>
</row>
<row>
<entry>
<para>SYSTEM_HALT</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>The system must be shut down quickly. An EPOW-aware OS
logs the EPOW error log information, then schedules the system
to be shut down in 20 seconds.</para>
</entry>
</row>
<row>
<entry>
<para>EPOW_MAIN_ENCLOSURE</para>
</entry>
<entry>
<para>5</para>
</entry>
<entry>
<para>The system may lose power. The hardware ensures that at
least 4 milliseconds of power within operational thresholds is
available after signalling an interrupt. An EPOW-aware OS
performs any desired functions, masks the EPOW interrupt, and
monitors the sensor to see if the condition changes. Hardware
does not clear this action code until the system resumes
operation within safe power levels.</para>
</entry>
</row>
<row>
<entry>
<para>EPOW_POWER_OFF</para>
</entry>
<entry>
<para>7</para>
</entry>
<entry>
<para>The system will lose power. The hardware ensures that at
least 4 milliseconds of power within operational thresholds is
available after signalling an interrupt. An EPOW-aware OS
performs any desired operations, then attempts to turn system
power off. An EPOW-aware OS does not clear the EPOW interrupt
for this action code. This action code is the highest
priority.</para>
</entry>
</row>
</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
longer present. For instance, a system might see a WARN_POWER action code
for a loss of a redundant line input power. EPOW_RESET may subsequently
be issued if the line power were restored. The same bits in the EPOW
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
power were restored, generating the EPOW_RESET EPOW would indicate that
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>

711
Error Handling/sec_rtas_error_indications.xml
Unescape Escape View File

@ -0,0 +1,711 @@
<?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="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
<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
need to be prepared to encounter the errors reported as they are
described here. However, in some platforms more sophisticated handling
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
primary architectural mechanism for indicating hardware errors to an OS
is the machine check interrupt. If an error condition is surfaced by
placing the system in checkstop, it precludes any immediate participation
by the OS in handling the error (that is, no error capture, logging,
recovery, analysis, or notification by the OS). For this reason, the
machine check interrupt is preferred over going to the checkstop state.
However, checkstop may be necessary in certain situations where further
processing represents an exposure to loss of data integrity. To better
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
<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
is enabled from software or firmware by setting the MSRME bit =1. Upon
the occurrence of a machine check interrupt, bits in SRR1 will indicate
the source of the interrupt and SRR0 will contain the address of the next
instruction that would have been executed if the interrupt had not
occurred. Depending on where the error is detected, the machine check
interrupt may be surfaced from within the processor, via logical
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"
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
<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"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>For
hardware-detected errors, platforms must generate error indications as
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"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Platforms which detect and report the
errors described in
<xref linkend="dbdoclet.50569337_30773"/> must provide information to the OS
via the RTAS
<emphasis>check-exception</emphasis> function, using the reporting format
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"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>To prevent error
propagation and allow for synchronization of error handling, all
processors in a multi-processor system must receive any machine check
interrupt signaled via the external machine check interrupt pin.</para>
</listitem>
</varlistentry>
</variablelist>

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

<orderedlist>
<listitem>
<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,
although this requirement hints at the use of a less severe
platform-specific interrupt for some errors. The important point here is
actually whether the error can be handled through that interrupt. Simply
using an external interrupt to signal the error is not sufficient. The
hardware and RTAS also need to limit the propagation of corrupted data,
prevent loss of error state data, and support the cleanup and recovery of
such an error. Since the response to an external interrupt may be
significantly slower than a machine check, and in fact may be masked, the
error should not require immediate action on the part of the OS and/or
RTAS. In addition, external interrupts (except external machine check
interrupts) are reported to only one processor, so operations by the
other processors in an MP system should not be impacted by this error
unless they specifically try to access the failing hardware element. To
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
<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
<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
errors signaled via the external machine check interrupt pin, that is not
the case for internal processor errors or processor bus errors.
Typically, only one processor will see such errors. An internal processor
error can be identified with just the contents of SRR1, and so can be
handled without synchronization with other processors. Processor bus
errors, however, can be more difficult, especially if the error is
propagated up to the processor bus from a lower-level bus. In general,
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
during the types of data transfer operations listed below. The assumption
here is that the error notification can occur only if a hardware
mechanism for error detection (for example, a parity checker) is present.
In cases where there is no specific error detection mechanism, the
resulting condition, and whether the software will eventually recognize
that condition as a failure, is undefined.</para>
<para>&#160;</para>
<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*" />
<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>
<para>
<emphasis role="bold">Initiator</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Target</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Operation</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Error Type(if detected)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Indication to Software</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Comments</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Processor</para>
</entry>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>Internal</para>
</entry>
<entry>
<para>Various</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>Some may cause checkstop</para>
</entry>
</row>
<row>
<entry morerows="11">
<para>Processor</para>
</entry>
<entry morerows="11">
<para>Memory</para>
</entry>
<entry morerows="4">
<para>Load</para>
</entry>
<entry>
<para>Invalid address</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>System bus time-out</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Address parity on system bus</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Data parity on system bus</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Memory parity or uncorrectable ECC</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>Store</para>
</entry>
<entry>
<para>Invalid address</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>System bus time-out</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Address parity on system bus</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Data parity on system bus</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>External cache load</para>
</entry>
<entry>
<para>Memory parity or uncorrectable ECC</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>Associated with Instruction Fetch or Data Load</para>
</entry>
</row>
<row>
<entry>
<para>External cache flush</para>
</entry>
<entry>
<para>Cache parity or</para>
<para>uncorrectable ECC</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>External cache access</para>
</entry>
<entry>
<para>Cache parity or</para>
<para>uncorrectable ECC</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>Associated with Instruction Fetch or Data Transfer</para>
</entry>
</row>
<row>
<entry>
<para>Processor</para>
</entry>
<entry>
<para>I/O</para>
</entry>
<entry>
<para>Load or Store</para>
</entry>
<entry>
<para>Various errors between the processor and the I/O
fabric</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>I/O fabrics include hubs and bridges and interconnecting
buses or links.</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>Processor</para>
</entry>
<entry morerows="3">
<para>I/O bus configuration space</para>
</entry>
<entry morerows="1">
<para>Read</para>
</entry>
<entry>
<para>Various, except no response from IOA</para>
</entry>
<entry>
<para>Firmware receives a machine check, OS receives
all=1&#8217;s data along with a
<emphasis>Status</emphasis> of -1 from the RTAS call</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, firmware does not get
a machine check and the PE is in the EEH Stopped State on
return from the RTAS call</para>
</entry>
</row>
<row>
<entry>
<para>No response from an IOA</para>
</entry>
<entry>
<para>All-1&#8217;s data returned, along with a
&#8220;Success&#8221;
<emphasis>Status</emphasis> from the RTAS call</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, the PE is not in the
EEH Stopped State on return from the RTAS call</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Write</para>
</entry>
<entry>
<para>Various, except no response from IOA</para>
</entry>
<entry>
<para>Firmware receives a machine check, OS receives a
<emphasis>Status</emphasis> of -1 from the RTAS call</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, firmware does not get
a machine check and the PE is in the EEH Stopped State on
return from the RTAS call</para>
</entry>
</row>
<row>
<entry>
<para>No response from an IOA</para>
</entry>
<entry>
<para>Operation ignored, OS receives a &#8220;Success&#8221;
<emphasis>Status</emphasis> from the RTAS call</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, the PE is in the EEH
Stopped State on return from the RTAS call</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>Processor</para>
</entry>
<entry morerows="3">
<para>I/O bus;</para>
<para>I/O Space</para>
<para>or</para>
<para>Memory Space</para>
</entry>
<entry morerows="1">
<para>Load</para>
</entry>
<entry>
<para>Various, except no response from IOA</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, no machine check is
received, all-1&#8217;s data is returned, and the PE enters the
EEH Stopped State</para>
</entry>
</row>
<row>
<entry>
<para>No response from an IOA</para>
</entry>
<entry>
<para>All-1&#8217;s data returned</para>
</entry>
<entry>
<para>Invalid address, broken IOA, or configuration cycle to
non-existent IOA; if EEH is implemented and enabled, the PE
enters the EEH Stopped State</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>Store</para>
</entry>
<entry>
<para>Various, except no response from IOA</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, no machine check is
received and the PE enters the EEH Stopped State</para>
</entry>
</row>
<row>
<entry>
<para>No response from IOA</para>
</entry>
<entry>
<para>Ignore Store</para>
</entry>
<entry>
<para>Invalid address, broken IOA, or configuration cycle to
non-existent IOA; if EEH is implemented and enabled, the PE
enters the EEH Stopped State</para>
</entry>
</row>
<row>
<entry>
<para>Processor</para>
</entry>
<entry>
<para>Invalid address (addressing an &#8220;undefined&#8221;
address area)</para>
</entry>
<entry>
<para>Load or Store</para>
</entry>
<entry>
<para>No response from system</para>
</entry>
<entry>
<para>Machine check</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>I/O</para>
</entry>
<entry>
<para>Memory</para>
</entry>
<entry>
<para>DMA - either direction</para>
</entry>
<entry>
<para>Various, including but not limited to:</para>
<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>

</entry>
<entry>
<para>Machine check unless reportable directly to the IOA in a
way that allows the IOA to signal the error to its device
driver</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, no machine check is
received and the PE enters the EEH Stopped State</para>
</entry>
</row>
<row>
<entry>
<para>I/O</para>
</entry>
<entry>
<para>I/O</para>
</entry>
<entry>
<para>DMA - either direction</para>
</entry>
<entry>
<para>Various</para>
</entry>
<entry>
<para>Machine check unless reportable to master of the transfer
in a way that allows master to recover</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>I/O</para>
</entry>
<entry>
<para>Invalid address</para>
</entry>
<entry>
<para>DMA - either direction</para>
</entry>
<entry>
<para>No response from any IOA</para>
</entry>
<entry>
<para>PCI IOA</para>
<para>master-aborts</para>
</entry>
<entry>
<para>Signal device driver using an external interrupt</para>
</entry>
</row>
<row>
<entry>
<para>PCI IOA</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>Any</para>
</entry>
<entry>
<para>Internal, indicated by SERR# or ERR_FATAL</para>
</entry>
<entry>
<para>SERR# or ERR_FATAL, causing machine check</para>
</entry>
<entry>
<para>If EEH is implemented and enabled, no machine check is
received and the PE enters the EEH Stopped State</para>
</entry>
</row>
</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
system state has not been lost, reporting these errors via a machine
check to the CPUs is inappropriate. Some devices or device drivers may
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>

40
Error Handling/sec_rtas_error_reporting_introduction.xml
Unescape Escape View File

@ -0,0 +1,40 @@
<?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="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
may have been analyzed to some degree by RTAS, and value judgments may
have been applied to decide how serious an error is, or even how to
describe it to the OS. These judgments are made by platform providers,
since only they know enough about the hardware to decide how serious a
problem it is, whether and how to recover from it, and how to map it onto
the abstracted set of events and errors that a system is required to know
about. There will be cases with some platforms where no reasonable
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>

37
Error Handling/sec_rtas_error_reporting_location_codes.xml
Unescape Escape View File

@ -0,0 +1,37 @@
<?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="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="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>

4055
Error Handling/sec_rtas_error_reporting_return_format.xml
View File

File diff suppressed because it is too large Load Diff

46
Error Handling/sec_rtas_hot_plug.xml
Unescape Escape View File

@ -0,0 +1,46 @@
<?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="Hot_Plug_Events">
<title>Hot Plug Events</title>
<para>Hot Plug Events, when implemented, are reported through the
event-scan RTAS call. These events are surfaced through the fixed
portions of the RTAS return value. (see
<xref linkend="dbdoclet.50569337_21249"/>) Some parts of the system may
be modified without direct support from the OS.</para>
<variablelist>
<varlistentry>
<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
without OS support, the Hot Plug Event mechanism must be provided for
signaling the OS about the event.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

176
LICENSE
Unescape Escape View File

@ -0,0 +1,176 @@

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.

"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:

(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.

You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

284
Platform/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>

284
Platform/app_eeh_handling.xml
Unescape Escape View File

@ -0,0 +1,284 @@
<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">

<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
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
Stopped and DMA Stopped state, and then doing one of the following:</para>

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

<listitem xml:id="dbdoclet.50569381_39262">
<para>Most general approach (detailed more in <xref linkend="dbdoclet.50569381_38095"/>): </para>
<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
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>
</listitem>

<listitem>
<para>Most robust (no reset unless necessary): </para>
<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
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
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>
</listitem>
</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
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:
error logging and error recovery.</para>
<para>These scenarios assume that:</para>

<orderedlist>
<listitem>
<para>The <emphasis> ibm,configure-pe</emphasis> RTAS call is implemented.</para>
</listitem>

<listitem>
<para>The attempts at recovery stop when Max_Retries_Exceeded is true.</para>
</listitem>
</orderedlist>

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

<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
the <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call.</para>
</listitem>

<listitem>
<para>The OS or device driver insures that all MMIOs to the IOA(s) in the PE are finished.</para>
</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
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
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">
<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
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,
and will eventually hit the same EEH event on further processing.</para>
</listitem>
</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,
Memory Space Enable, etc.). </para>
</listitem>

<listitem xml:id="dbdoclet.50569381_29191">
<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
State (as it should be in step #<xref linkend="dbdoclet.50569381_59303"/>). </para>
<orderedlist numeration="loweralpha">
<listitem>
<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>
with <emphasis>Function</emphasis> 1(Temporary Error).</para>
</listitem>
</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
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
<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,
otherwise stop and mark the IOA(s) in the PE as unusable.</para>
</listitem>
</orderedlist>
</section>

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

<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
another EEH event. </para>
<orderedlist numeration="loweralpha">
<listitem>
<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>

<listitem>
<para>The minimum reset active time is waited.</para>
</listitem>

<listitem>
<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
longer time, instead.</para>
</listitem>
</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
the same EEH event on further processing.</para></note>
</para>
</listitem>

<listitem>
<para>The device driver restores the PCI configuration spaces of the IOA(s) in the PE.</para>
</listitem>

<listitem>
<para>The device driver initializes the IOA for operations.</para>
</listitem>
</orderedlist>

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

1289
Platform/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

121
Platform/bk_main.xml
Unescape Escape View File

@ -0,0 +1,121 @@
<?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>Platform</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</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.0_pre1</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 for the base Platform hardware associated with an OpenPOWER Systems.
The base content for this document were contributed to the OpenPOWER Foundation in the
<citetitle>IBM Linux on Power Architecture Platform Reference (LoPAPR) Draft</citetitle>
document. It 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>2016-05-04</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Revision 2.0_pre1 - initial conversion from IBM document. Extracted from
Linux on Power Architecture Platform Reference (LoPAPR) version 1.1 dated March 24,
2016 -- Chapter 1 (Introduction), Chapter 2 (System Requirements),
Chapter 3 (Address Map), Chapter 4 (I/O Bridges and Topology),
Chapter 5 (Processors and Memory), Chapter 6 (Interrupt Controller),
Chapter 8 (Non-volatile memory), Chapter 9 (I/O Devices),
Chapter 11 (The Symmetric Multiprocessor Option), Chapter 12 (Product Topology),
and Appendix H (Non-Uniform Memory Access [NUMA] Option).</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>

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

<!-- Chapter heading files -->
<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_interrupt_controller.xml"/>
<xi:include href="ch_nonvolatile_memory.xml"/>
<xi:include href="ch_smp.xml"/>
<xi:include href="ch_numa.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_eeh_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>

1132
Platform/ch_address_map.xml
View File

File diff suppressed because it is too large Load Diff

726
Platform/ch_interrupt_controller.xml
Unescape Escape View File

@ -0,0 +1,726 @@
<?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
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="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
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>
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
linkend="dbdoclet.50569331_33067"/>.</para>

<variablelist>
<varlistentry>
<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
Interrupt</citetitle>. </para>
</listitem>
</varlistentry>
<varlistentry>
<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
root node.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
node.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
single OS image must be all unique.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
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"
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
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"
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
corresponding node generating the interrupt. </para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
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>
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
interrupt.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
Storage mapping.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
of the active processors.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
OS has taken explicit action.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
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
level.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
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"
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
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"
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
source controller node.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
presentation controller node.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
interrupt presentation controller node.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

<section>
<title>PowerPC External Interrupt Option Properties</title>
<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="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
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>,
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).
<xref linkend="dbdoclet.50569331_99447"/> summarizes the LSI and MSI support.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569331_99447">
<title>LSI and MSI Support Requirements and Initial Assignment </title>
<tgroup cols="7">
<colspec colname="c1" colwidth="14*" align="center"/>
<colspec colname="c2" colwidth="14*" align="center"/>
<colspec colname="c3" colwidth="14*" align="center"/>
<colspec colname="c4" colwidth="14*" align="center"/>
<colspec colname="c5" colwidth="14*" align="center"/>
<colspec colname="c6" colwidth="14*" align="center"/>
<colspec colname="c7" colwidth="14*" align="center"/>
<thead valign="middle">
<row>
<entry morerows="1">
<para>
<emphasis role="bold">IOA Type</emphasis>
</para>
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">LSI required by PCI specifications?</emphasis>
</para>
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">MSI or MSI-Xrequired by PCI specifications?</emphasis>
</para>
</entry>
<entry morerows="1">
<para>
<emphasis role="bold">Bridge between IOA and PHB</emphasis>
</para>
</entry>
<entry nameend="c6" namest="c5">
<para>
<emphasis role="bold">Possible platform support</emphasis>
</para>
</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
configuration space.</para></footnote></emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>If PHB does not support MSI option<?linebreak?>
(Not including PCI Express HBs)</para>
</entry>
<entry>
<para>If PHB supports MSI option<?linebreak?>
(Including all PCI Express HBs)</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>PCI</para>
</entry>
<entry>
<para>When interrupts are required</para>
</entry>
<entry>
<para>No<?linebreak?>
(allowed; optional)</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>LSI</para>
</entry>
<entry>
<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
<emphasis>ibm,change-msi</emphasis> RTAS call.</para></footnote></para>
</entry>
</row>
<row>
<entry>
<para>PCI-X</para>
</entry>
<entry>
<para>Encouraged when interrupts are required, for backward
platform compatibility</para>
</entry>
<entry>
<para>Yes</para>
</entry>
<entry>
<para>-</para>
</entry>
<entry>
<para>LSI</para>
</entry>
<entry>
<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
<emphasis>ibm,change-msi</emphasis> RTAS call.</para></footnote></para>
</entry>
</row>
<row>
<entry morerows="1">
<para>PCI Express</para>
</entry>
<entry morerows="1">
<para>Discouraged<?linebreak?>
(expect IOAs to not implement in most cases)</para>
</entry>
<entry morerows="1">
<para>Yes</para>
</entry>
<entry>
<para>None or PCI Express switch only</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<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
space.</para></footnote></para>
</entry>
</row>
<row>
<entry>
<para>Reverse bridge<?linebreak?>
(primary, PCI Express secondary)</para>
</entry>
<entry>
<para>LSI or not supported<footnote xml:id="pgfId-1001611">
<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
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
call.</para></footnote></para>
</entry>
</row>
</tbody>
</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
implemented.</para>

<variablelist>
<varlistentry>
<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
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
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
The platform must implement the PowerPC External Interrupt option.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
and <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS calls.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
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
PE).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569331_63544">
<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
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
be required, and not just a unique port per PE.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
platform to interrupt.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
IOA at all the following times:</para>

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

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

<listitem>
<para>During the <emphasis>ibm,change-msi</emphasis> or
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<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
interrupts at all the following times:</para>

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

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

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

<listitem>
<para>During the <emphasis>ibm,change-msi</emphasis> or
<emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<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
<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"
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
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
implemented to take into consideration that possibility.</para>
</listitem>
</varlistentry>
</variablelist>

</section>
</section>

<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>
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"
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>
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"
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
priority levels 0x00 through 0x07 and 0xFF for internal use. </para>
</listitem>
</varlistentry>
</variablelist>

</section>
</chapter>

989
Platform/ch_io_devices.xml
Unescape Escape View File

@ -0,0 +1,989 @@
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title>I/O Devices</title>

<para>This chapter describes requirements for IOAs. It adds detail to areas
of the PCI architectures (conventional PCI, PCI-X and PCI Express) that are
either unaddressed or optional. It also places some requirements on firmware
and the OS for IOA support. It provides references to specifications to which
IOAs must comply and gives design notes for IOAs that run on LoPAR systems.
</para>
<section xml:id="sec_pci_ioas">
<title>PCI IOAs</title>


<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pci_ioas"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>All PCI IOAs must be capable of decoding and
generating either a full 32-bit address or a full 64-bit address.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569335_14547">
<term><emphasis role="bold">R1-<xref linkend="sec_pci_ioas"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>IOAs that implement conventional PCI must be compliant with the
most recent version of the <xref linkend="dbdoclet.50569387_65468"/> at the
time of their design, including any approved Engineering Change Requests (ECRs)
against that document. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pci_ioas"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>IOAs that implement PCI-X must be compliant
with the most recent version of the <xref linkend="dbdoclet.50569387_26550"/>
at the time of their design, including any approved Engineering Change Requests
(ECRs) against that document. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pci_ioas"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>IOAs that implement PCI Express must be
compliant with the most recent version of the <xref
linkend="dbdoclet.50569387_66784"/> at the time of their design, including any
approved Engineering Change Requests (ECRs) against that document</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Architecture Note:</emphasis> Revision 2.1 and later of
the <emphasis>PCI Local Bus Specification</emphasis> requires that PCI masters
which receive a Retry target termination to unconditionally repeat the same
request until it completes. The master may perform other bus transactions, but
cannot require those to complete before repeating the original transaction
which was previously target terminated with Retry. Revision 2.1 of the
specification (page 49) also includes an example which describes how the
requirement above applies to a multi-function IOA. See page 48-49 of the 2.1
revision of the <emphasis>PCI Local Bus Specification</emphasis> for more
detail. Revision 2.0 of the <emphasis>PCI Local Bus Specification</emphasis>
includes a definition of target termination via Retry, but did not spell out
the requirement described above for masters, as does the 2.1 revision of the
specification. Masters which are designed based on revision 2.0 of the
specification that perform other transactions following target termination with
Retry, may cause live-locks and/or deadlocks when installed in a system that
utilizes bridges (host bridge or PCI-PCI bridges) that implement Retry, delayed
transactions, and/or TCEs, when those masters require following transactions to
complete before the original transaction that was terminated with the target
Retry. This revision 2.0 to revision 2.1 compatibility problem has been
observed on several IOAs that have asked for deviations to Requirement <xref
linkend="dbdoclet.50569335_14547"/>. Wording was added to the revision 2.2 of
the <emphasis>PCI Local Bus Specification</emphasis> which makes a statement
similar to this Architecture Note.</para>
<section xml:id="dbdoclet.50569335_36981">
<title>Resource Locking</title>

<variablelist>
<varlistentry xml:id="dbdoclet.50569335_16015">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_36981"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>PCI IOAs, excepting bridges, must not depend on the PCI LOCK#
signal for correct operation nor require any other PCI IOA to assert LOCK# for
correct operation.</para>
</listitem>
</varlistentry>
</variablelist>

<para>There are some legacy IOAs on legacy buses which require LOCK#.
Additionally, LOCK# is used in some implementations to resolve deadlocks
between bridges under a single PHB. These uses of LOCK# are permitted. </para>
</section>

<section xml:id="dbdoclet.50569335_12219">
<title>PCI Expansion ROMs</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_12219"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>PCI expansion ROMs must have a ROM image
with a code type of 1 for OF as provided in the <xref
linkend="dbdoclet.50569387_65468"/>. This ROM image must abide by the ROM image
format for OF as documented in the <xref
linkend="dbdoclet.50569387_22451"/>.</para>
</listitem>
</varlistentry>
</variablelist>

<para>LoPAR systems rely on OF - not BIOS - to boot. This is why strong
requirements for OF device support are made.</para>
<para>Vital Product Data (VPD) is an optional feature for PCI adapters
and it is strongly recommended that VPD be included in all PCI expansion ROMs.
If it is put in the PCI expansion ROM in accordance with the <xref
linkend="dbdoclet.50569387_65468"/>, VPD will be reported in the OF device
tree. If the VPD information is formatted as defined in Revision 2.2 with the
new capabilities feature, or in any other format, firmware will not read the
VPD, and the device driver for the IOA will have to reformat any provided VPD
into an OS specified format. It is still required that the keywords and their
values must conform to those specified by either PCI 2.1 or PCI 2.2, no matter
how they are formatted. Refer to Requirement <xref
linkend="dbdoclet.50569341_65980"/>. </para>
</section>

<section xml:id="dbdoclet.50569335_35146">
<title>Assignment of Interrupts to PCI IOAs</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_35146"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>All PCI IOAs must use the PowerPC
interrupt controller, except when made transparent to the OS by the platform
through the architected hcall()s. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_35146"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>PCI IOAs that do not reside in the
Peripheral Memory Space and Peripheral I/O Space of the same PHB must not share
the same LSI source.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For further information on the interrupt controller refer to <xref
linkend="dbdoclet.50569331_37856"/>. </para>
<para>It is strongly advised that system board designers assign one
interrupt for each interrupt source. Additionally, multi-function PCI IOAs
should have multiple interrupt sources. For restrictions on sharing interrupts
with the LPAR option, see Requirement <xref linkend="LoPAR.Virtualization"/>.
For restrictions on sharing MSIs, see Requirement <xref
linkend="dbdoclet.50569331_84312"/> and Requirement <xref
linkend="dbdoclet.50569331_63544"/>.</para>
</section>

<section xml:id="sec_pci_bridges">
<title>PCI-PCI Bridge Devices</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pci_bridges"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Firmware must initialize all PCI-to-PCI
bridges. See <xref linkend="dbdoclet.50569387_22451"/>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>All bridges and switches are required to comply with the bus
specification(s) of the buses to which they are attached. See Requirement <xref
linkend="dbdoclet.50569330_95825"/>.</para>
</section>

<section xml:id="sec_graphics">
<title>Graphics Controller and Monitor Requirements for Clients</title>
<para>The graphics requirements for servers are different from those for
portable and personal systems. </para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_graphics"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Plug-in graphics controllers for portable
and personal platforms must provide graphics mode sets in the OF PCI expansion
ROM image in accordance with the
<xref linkend="dbdoclet.50569387_22451"/>.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Portable and personal platforms are strongly urged to support some
mechanism which allows the platform to electronically sense the display
capabilities of monitors. </para>

<para>For graphics controllers that are placed on the system board, the
graphics mode sets can be put in system ROM. The mode set software put in the
system ROM in this case would be FCode and would be largely or entirely the
same as the FCode that would be in the PCI expansion ROM if the same graphics
controller was put on a plug-in PCI card.</para>
</section>

<section xml:id="dbdoclet.50569335_21614">
<title>PCI Plug-in Graphic Cards</title>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_21614"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis>(Requirement Number Reserved
For Compatibility)</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569335_21614"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>PCI plug-in graphics cards which are
going to be the primary display IOA during the time prior to the OS device
driver being loaded must contain an OF display driver on the IOA.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_pci_cache">
<title>PCI Cache Support Protocol</title>
<para>The PCI architecture allows for the optional implementation of
caching of data. This architecture basically assumes that the data in I/O
memory is non-coherent. As such, platforms are not required to implement the
optional PCI Cache Support protocol using the SBO# and SDONE signals.
Therefore, IOAs used in LoPAR platforms should not count on those signals for
proper operations.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569335_39614">
<term><emphasis role="bold">R1-<xref linkend="sec_pci_cache"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>IOAs used in LoPAR platforms
and their device drivers must not require the use of the PCI signals SBO# and
SDONE for proper operations. </para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_pci_config_space">
<title>PCI Configuration Space for IOAs</title>
<para>There are several writable fields in the PCI Configuration Header.
Some of these are written by the firmware and should never be changed by the
device driver. </para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569335_13568">
<term><emphasis role="bold">R1-<xref linkend="sec_pci_config_space"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>All registers and bits in the PCI Configuration Header must be
set to a platform specific value by firmware and preserved by software, except
that software is responsible for setting the configuration space as indicated
in <xref linkend="dbdoclet.50569335_27772"/>.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569335_27772">
<title>Software Programming of PCI Configuration Header Registers</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center"/>
<colspec colname="c2" colwidth="20*" align="center"/>
<colspec colname="c3" colwidth="60*"/>
<thead>
<row>
<entry>
<para> Register Name</para>
</entry>
<entry>
<para> Bit Name</para>
</entry>
<entry align="center">
<para> Software Action</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="3">
<para> Command</para>
</entry>
<entry>
<para> Bus Master</para>
</entry>
<entry>
<para> Must write to a 1 before the first DMA operation after a
reset. Must write to a 0 before unconfiguring device driver.</para>
</entry>
</row>
<row>
<entry>
<para> Memory Space</para>
</entry>
<entry>
<para> Must write to a 1 before the first MMIO operation to
IOA&#x2019;s memory space (if any) after a reset. Must write to a 0 before
unconfiguring device driver.</para>
</entry>
</row>
<row>
<entry>
<para> IO Space</para>
</entry>
<entry>
<para> Must write to a 1 before the first MMIO operation to
IOA&#x2019;s I/O space (if any) after a reset. Must write to a 0 before
unconfiguring device driver.</para>
</entry>
</row>
<row>
<entry>
<para> all other bits</para>
</entry>
<entry>
<para> Must restore to previous value after any reset operation
(for example, via <emphasis>ibm,set-slot-reset Function</emphasis> 1 or 3).
The <emphasis>ibm,configure-bridge</emphasis> RTAS call is available to assist
in restoring values, where appropriate.</para>
</entry>
</row>
<row>
<entry>
<para> Built in Self Test (BIST)</para>
</entry>
<entry>
<para> all</para>
</entry>
<entry>
<para> If implemented, software may use if desired.</para>
</entry>
</row>
<row>
<entry>
<para> all other PCI header registers that may be modified by
firmware after initial reset or by <emphasis>ibm,configure-connector</emphasis> for DR operations</para>
</entry>
<entry>
<para> all</para>
</entry>
<entry>
<para> Must restore to previous value after any reset operation
(for example, via <emphasis>ibm,set-slot-reset-state Function</emphasis> 1).
The <emphasis>ibm,configure-bridge</emphasis> RTAS call is available to assist
in configuring PCI bridges and switches, where appropriate.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569335_17839">
<term><emphasis role="bold">R1-<xref linkend="sec_pci_config_space"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>All IOAs that implement PCI-X Mode 2 or PCI Express must supply
the <emphasis role="bold"><literal>&#x201C;ibm,pci-config-space-type&#x201D;</literal></emphasis> property
(see <xref linkend="LoPAR.RTAS"/>).</para>
<para><emphasis role="bold">Implementation Note:</emphasis> The
<emphasis role="bold"><literal>&#x201C;ibm,pci-config-space-type&#x201D;</literal></emphasis>
property in Requirement <xref linkend="dbdoclet.50569335_17839"/> is added for platforms that support
I/O fabric and IOAs that implement PCI-X Mode 2, and PCI Express. To access the
extended configuration space provided by PCI-X Mode 2 and PCI Express, all I/O
fabric leading up to an IOA must support a 12-bit register number. In other
words, if a platform implementation has a conventional PCI bridge leading up to
an IOA that implements PCI-X Mode 2, the platform will not be able to provide
access to the extended configuration space of that IOA. The
<emphasis role="bold"><literal>&#x201C;ibm,config-space-type&#x201D;</literal></emphasis> property in the IOA's OF node
is used by device drivers to determine if an IOA&#x2019;s extended
configuration space can be accessed. </para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_ioa_bus_memory_space">
<title>PCI IOA Use of PCI Bus Memory Space Address 0</title>
<para>Some PCI IOAs will fail when given a bus address of 0. In the PC
world, address 0 would not be a good address, so some PCI IOA designs which
were designed for the PC arena will check for an address of 0, and fail the
operation if it is 0. </para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569335_30300">
<term><emphasis role="bold">R1-<xref linkend="sec_ioa_bus_memory_space"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For systems that use PCI IOAs
which will fail when given a bus address of 0 for DMA operations, and when the
operations for which those IOAs are used are other than system memory dump
operations, then the OS must prevent the mapping of PCI bus address 0 for PCI
DMA operation for such IOAs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ioa_bus_memory_space"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>PCI IOAs used for dumping contents of
system memory must operate properly with a PCI bus address of 0 for PCI DMA
operations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ioa_bus_memory_space"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The firmware must not map an IOA used for
loading a boot image to an address of 0, when loading a boot image, if that IOA
cannot accept an address of 0.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Implementation Note:</emphasis> A reasonable
implementation of Requirement <xref linkend="dbdoclet.50569335_30300"/> would
be to have an interface between the device driver and the kernel to allow the
device driver to indicate to the kernel that the restriction is required for
that IOA, so that all IOAs for that kernel image are not affected.</para>
</section>

<section xml:id="sec_pcie_comp_timeout">
<title>PCI Express Completion Timeout</title>
<para>Prior to the implementation of the PCI Express additional
capability to set the Completion Timeout Value and Completion Timeout Disable
in the PCI Express Device Control 2 register of an IOA, the IOAs need
device-specific way to provide the disable capability. In addition, the
platforms need to provide a way for the OSs and device drivers to know when to
disable the completion timeout of these devices that only provide a
device-specific way of doing so.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pcie_comp_timeout"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>PCI Express IOAs must either provide a
device-specific way to disable their DMA Completion Timeout timer or must
provide the Completion Timeout Disable or Completion Timeout Value capability
in the PCI Express Device Control 2 register, and device drivers for IOAs that
provide a device-specific way must disable their DMA Completion Timeout timer
if it is either unknown whether the IOA provides a sufficiently long timer
value for the platform, or if it is known that they do not provide a sufficient
timeout value (for example, if the
<emphasis role="bold"><literal>&#x201C;ibm,max-completion-latency&#x201D;</literal></emphasis> property is not
provided).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569335_65475">
<term><emphasis role="bold">R1-<xref linkend="sec_pcie_comp_timeout"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Platforms must provide the
<emphasis role="bold"><literal>&#x201C;ibm,max-completion-latency&#x201D;</literal></emphasis> property in
each PCI Express PHB node of the OF Device Tree.</para>
</listitem>
</varlistentry>
</variablelist>

</section>

<section xml:id="sec_pcie_iov">
<title>PCI Express I/O Virtualized (IOV) Adapters</title>
<para>PCI Express defines I/O Virtualized (IOV) adapters, where such an
adapter has separate resources for each virtual instance, called a Virtual
Function (VF). There are two PCI specifications that exist to define such
adapters:</para>

<itemizedlist>
<listitem>
<para><xref linkend="dbdoclet.50569387_94229"/> defines the
requirements for SR-IOV adapters.</para>
</listitem>
<listitem>
<para><xref linkend="dbdoclet.50569387_42471"/> defines the
requirements for MR-IOV adapters.</para>
</listitem>
</itemizedlist>

<para>The interface presented to an OS from an MR-IOV adapter will look
the same as an SR-IOV adapters, and therefore will not be described separately
here.</para>
<para>IOV adapters and/or the VFs of an IOV adapter that has IOV enabled,
are assigned to OSs as follows (see also <xref
linkend="dbdoclet.50569335_70133"/> for a full set of characteristics of these
environments):</para>
<itemizedlist>
<listitem>
<para>For the <emphasis>Legacy Dedicated</emphasis> environment, the
entire adapter is assigned to one LPAR, with the IOV functionality not enabled.
In this mode, the OS provides device driver(s) for the adapter Function(s). VFs
do not exist, because IOV is not enabled. The OS is given the capability to do
Hot Plug add, remove, and replace in a non-managed environment (without an
HMC), and may be given that capability in a managed environment. </para>
</listitem>
<listitem>
<para>For the <emphasis>SR-IOV Non-shared</emphasis> environment, the
entire adapter is assigned to one LPAR, with IOV functionality enabled, but
with the Physical Function(s) (PFs) of the adapter hosted by the platform. Only
VFs are presented to the OS. The OS is given the capability to do Hot Plug add,
remove, and replace in a non-managed environment (without an HMC), and may be
given that capability in a managed environment. </para>
</listitem>
<listitem>
<para>For the <emphasis>SR-IOV Shared</emphasis> environment, the
adapter is assigned to the platform, with IOV functionality enabled. The
platform then assigns VF(s) to OS(s). Only the managed environment applies, and
add/remove/replace operations are controlled by DLPAR operations to the OS(s)
from the management console.</para>
</listitem>
</itemizedlist>

<para>For all environments except the SR-IOV Shared, multiple functions
will appear as a multi-function IOA with possible sharing of a single PE. For
example, the multi-function adapters may have a shared EEH domain and shared
DMA window.</para>
<para>Determination of which of the above environments is supported for a
given platform and partition or OS type is beyond the scope of this
architecture.</para>
<para><xref linkend="dbdoclet.50569335_70133"/> defines the
characteristics of these environments.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569335_70133">
<title>IOV Environment Characteristics </title>
<tgroup cols="4">
<colspec colname="c1" colwidth="55*"/>
<colspec colname="c2" colwidth="15*" align="center"/>
<colspec colname="c3" colwidth="15*" align="center"/>
<colspec colname="c4" colwidth="15*" align="center"/>
<thead>
<row>
<entry>
<para>
<emphasis role="bold">&#xA0;</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Legacy Dedicated</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">SR-IOV Non-shared</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">SR-IOV Shared</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Entire adapter assigned to OS, IOV not enabled</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<para>n/a</para>
</entry>
</row>
<row>
<entry>
<para> Entire adapter assigned to OS, IOV enabled</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>n/a</para>
</entry>
</row>
<row>
<entry>
<para>Adapter can be shared across multiple OSs, IOV enabled</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para>Function DD support</para>
</entry>
<entry>
<para>Plain Function only<?linebreak?>
(not VF or PF) </para>
</entry>
<entry>
<para>VF only</para>
</entry>
<entry>
<para>VF only</para>
</entry>
</row>
<row>
<entry>
<para>PFs managed by platform?</para>
</entry>
<entry>
<para>n/a</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para>Managed environment support?</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para>Non-managed environment support?</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry>
<para>OS controlled Hot Plug capable?</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry>
<para>DLPAR capable?</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para>All functions under one PHB in the OF Device Tree for the adapter?</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry>
<para>All functions under separate PHBs in the OF Device Tree
for the same adapter<footnote xml:id="pgfId-545449"><para>The adapter is
physically under one PHB, but the platform creates separate
&#x201C;virtual&#x201D; PHBs in the OF Device Tree and virtualizes the PCI
Express configuration space for the various functions.</para></footnote>?</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para><emphasis>config_addr</emphasis> translation
(virtualization) by the platform (that is, the bus/device/function of the
<emphasis>config_addr</emphasis> does not necessarily correspond to what the
device has programmed)</para>
</entry>
<entry>
<para>no</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<para>Shared PE domain (for example, shared EEH domain, shared DMA window)</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>yes</para>
</entry>
<entry>
<para>no</para>
</entry>
</row>
</tbody>
</tgroup>
</table>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pcie_iov"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>PCI Express Single Root IOV (SR-IOV)
adapters must comply to the <xref linkend="dbdoclet.50569387_94229"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pcie_iov"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>PCI Express Multi-Root IOV (MR-IOV)
adapters must comply to the <xref linkend="dbdoclet.50569387_42471"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pcie_iov"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The platform must present within the
device tree nodes for all PCI Express adapters configured to operate in IOV
mode the <emphasis role="bold"><literal>"ibm,is-vf"</literal></emphasis> property as defined in section
<xref linkend="LoPAR.RTAS"/>. </para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>

<section xml:id="sec_multi_init_scsi">
<title>Multi-Initiator SCSI Support</title>
<para>Multi-initiator SCSI support is identified in the OF device tree.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_multi_init_scsi"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">Platform Implementation:</emphasis>
Platforms must support the <emphasis role="bold"><literal>&#x201C;scsi-initiator-id&#x201D;</literal></emphasis>
property as described in <xref linkend="LoPAR.DeviceTree"/> and <xref linkend="dbdoclet.50569387_27008"/>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_contig_mem">
<title>Contiguous Memory </title>
<para>I/O devices that require contiguous memory pages (either real or via
contiguous TCEs) cannot reasonably be accommodated in LoPAR platforms. When
TCEs are turned off, that would require that real physical memory addresses be
allocated. When TCEs are on, that would require contiguous TCEs be assigned,
and although that is the first attempt by the OS&#x2019;s TCE assignment
algorithm, the algorithm will assign non-contiguous ones if contiguous ones
cannot be assigned. Dynamic Reconfiguration complicates the contiguous problem
even further.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_contig_mem"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>I/O devices and/or their device drivers used
in LoPAR platforms must implement scatter/gather capability for DMA operations
such that they do not require contiguous memory pages to be allocated for
proper operation. </para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_redirect_serial_ports">
<title>Re-directed Serial Ports</title>
<para>The <emphasis role="bold"><literal>&#x201C;ibm,vty-wrap-capable&#x201D;</literal></emphasis> OF
device tree property will be present in an OF device tree of a serial port node
when the OS data communication with that serial port controller can be
redirected, or wrapped, away from the physical serial port connector to an
<emphasis>ibm,vty</emphasis> device, which is often a virtual terminal session
of the Hardware Management Console (HMC). This property indicates to serial
port diagnostic programs that additional end user information should be
displayed during the serial port diagnostic test indicating that it is possible
that serial port data could be redirected away from the physical serial port
preventing the execution of wrap tests with physical wrap plugs. The end user
information should describe that initiating a virtual terminal session causes
the serial port controller's data to be wrapped away from the physical serial
port connection and that terminating a virtual terminal session causes the
serial port controller's data to be returned to the physical serial port
connection. The <emphasis role="bold"><literal>&#x201C;ibm,vty-wrap-capable&#x201D;</literal></emphasis>
property is present with a value of null when this re-direction capability
exists and is absent when this capability does not exist. </para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_redirect_serial_ports"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The <emphasis role="bold"><literal>&#x201C;ibm,vty-wrap-capable&#x201D;</literal></emphasis>
OF device tree property must
be present in an OF device tree of a serial port node when the OS data
communication with that serial port controller can be redirected, or wrapped,
away from the physical serial port connector to an ibm,vty device, and must not
be present if this capability does not exist.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_sys_bus_ioas">
<title>System Bus IOAs</title>
<para>This section lists the requirements for the systems to support IOAs
connected to the system bus or main I/O expansion bus.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Each system bus IOA must be a bus
master.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Firmware must assign unique addresses to all
system bus IOA facilities. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Addresses assigned to system bus IOA
facilities must not conflict with the addresses mapped by any host bridge on
the system bus.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>System bus IOAs must be assigned interrupt
sources for their interrupt requirements by firmware. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>A system bus IOA&#x2019;s OF
<emphasis role="bold"><literal>&#x201C;interrupts&#x201D;</literal></emphasis> property must reflect
the interrupt source and type allocation for the device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>All system bus IOA interrupts must be low
true level sensitive (referred to as level sensitive).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>Interrupts assigned to system bus IOAs must
not be shared with other IOAs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para> The OF unit address (first entry of the
<emphasis role="bold"><literal>&#x201C;reg&#x201D;</literal></emphasis> property) of a system
bus IOA must stay the same from boot to boot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_sys_bus_ioas"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para>Each system bus IOA must have documentation
for programming the IOA and an OF binding which describes at least the
<emphasis role="bold"><literal>&#x201C;name&#x201D;</literal></emphasis>,
<emphasis role="bold"><literal>&#x201C;reg&#x201D;</literal></emphasis>,
<emphasis role="bold"><literal>&#x201C;interrupts&#x201D;</literal></emphasis>, and
<emphasis role="bold"><literal>&#x201C;interrupt-parent&#x201D;</literal></emphasis>
properties for the device.</para>
</listitem>
</varlistentry>
</variablelist>

</section>
</chapter>

2610
Platform/ch_io_topology.xml
View File

File diff suppressed because it is too large Load Diff

740
Platform/ch_nonvolatile_memory.xml
Unescape Escape View File

@ -0,0 +1,740 @@
<?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
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"
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
OS beyond the first.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
contents in the absence of system power.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
bootable state if NVRAM data corruption is detected.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
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
limit the implementation choices.</para>
<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
<emphasis>signature</emphasis> and <emphasis>name</emphasis>). </para>

<variablelist>
<varlistentry>
<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
in <xref linkend="dbdoclet.50569333_37259"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
NVRAM partitions.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
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
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
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
corruption on system operation.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569333_37259">
<title>NVRAM Structure </title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center"/>
<colspec colname="c2" colwidth="15*" align="center"/>
<colspec colname="c3" colwidth="70*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Field Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para> signature</para>
</entry>
<entry>
<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
<xref linkend="dbdoclet.50569333_24820"/>.</para>
</entry>
</row>
<row>
<entry>
<para>checksum</para>
</entry>
<entry>
<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
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 */
{
unsigned char b_data; /* byte data */
unsigned char i_sum; /* intermediate sum */
unsigned char c_sum; /* current sum */
for (c_sum = 0; nbytes; nbytes--)
{
b_data = *bp++; /* read byte from buffer */
i_sum = c_sum + b_data; /* add to current sum */
if(i_sum < c_sum) /* did a carry out result? */
i_sum += 1; /* if so, add 1 */
c_sum = i_sum; /* copy to current sum */
}
return (c_sum);
}]]></programlisting></para>
<para>This checksum algorithm guarantees 0 to be an impossible
calculated value. A valid header cannot have a checksum of zero.</para>
</entry>
</row>
<row>
<entry>
<para> length</para>
</entry>
<entry>
<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
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
every NVRAM partition beyond it.</para>
</entry>
</row>
<row>
<entry>
<para> name</para>
</entry>
<entry>
<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
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
conflict is not created.</para>
</entry>
</row>
<row>
<entry>
<para> data</para>
</entry>
<entry>
<para><emphasis>length</emphasis> minus 16 bytes</para>
</entry>
<entry>
<para> The structure of the <emphasis>data</emphasis> area is
controlled by the creator/owner of the NVRAM partition.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569333_24820">
<title>NVRAM Signatures </title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center"/>
<colspec colname="c2" colwidth="15*" align="center"/>
<colspec colname="c3" colwidth="15*" align="center"/>
<colspec colname="c4" colwidth="15*" align="center"/>
<colspec colname="c5" colwidth="40*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Signature <?linebreak?>(see note)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Signature Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Ownership Class</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold"># Required</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para> 0x70</para>
</entry>
<entry>
<para> System</para>
</entry>
<entry>
<para> Global</para>
</entry>
<entry>
<para> 1</para>
</entry>
<entry>
<para> For configuration variables.</para>
</entry>
</row>
<row>
<entry>
<para> 0x7E</para>
</entry>
<entry>
<para> Vendor-defined </para>
</entry>
<entry>
<para> Global</para>
</entry>
<entry>
<para> 0 to n</para>
</entry>
<entry>
<para> &#x201C;name&#x201D; prefix required.</para>
</entry>
</row>
<row>
<entry>
<para> 0x7F</para>
</entry>
<entry>
<para> Free Space</para>
</entry>
<entry>
<para> Global</para>
</entry>
<entry>
<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
partitions must be set to 0x7...77.</para>
</entry>
</row>
<row>
<entry>
<para> 0xA0</para>
</entry>
<entry>
<para> OS</para>
</entry>
<entry>
<para> Any OS</para>
</entry>
<entry>
<para> 0 to n</para>
</entry>
<entry>
<para> General OS usage.</para>
</entry>
</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
reasons.</para>
</entry>
</row>
</tbody>
</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="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"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<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"
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
characters.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
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"
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
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>,
<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
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>
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
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,
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
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="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
boolean: </para>
<itemizedlist mark="none">
<listitem>
<para><emphasis role="bold"><literal>auto-boot?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>diag-switch?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>fcode-debug?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>oem-banner?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>oem-logo?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>use-nvramrc?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>little-endian?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>real-mode?</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>menu?</literal></emphasis> (see <xref linkend="dbdoclet.50569327_26247"/>). </para>
</listitem>
</itemizedlist>
</section>

<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
integer:</para>
<itemizedlist mark="none">
<listitem>
<para><emphasis role="bold"><literal>screen-#columns</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>screen-#rows</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>security-#badlogins</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>security-mode</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>selftest-#megs</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>real-base</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>real-size</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>virt-base</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>virt-size</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>load-base</literal></emphasis></para>
</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
string: </para>
<itemizedlist mark="none">
<listitem>
<para><emphasis role="bold"><literal>boot-command</literal></emphasis> [1]</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>boot-device</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>boot-file</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>diag-device</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>diag-file</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>input-device</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>nvramrc</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>oem-banner</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>output-device</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>security-password</literal></emphasis> [1] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>bootinfo-nnnnn</literal></emphasis> [*] </para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>reboot-command</literal></emphasis> [*]</para>
</listitem>
</itemizedlist>
</section>

<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
0xFF. The following configuration variables are of type bytes:</para>
<itemizedlist mark="none">
<listitem>
<para><emphasis role="bold"><literal>oem-logo</literal></emphasis> [1] </para>
</listitem>
</itemizedlist>
</section>
</section>
</section>

<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
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
before proceeding to subsequent drives (no overlap).</para>

<variablelist>
<varlistentry>
<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
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
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"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<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"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<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
consolidation may become necessary.</para>

<variablelist>
<varlistentry>
<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
partition, except OS and Free Space signature NVRAM partitions. </para>
</listitem>
</varlistentry>
<varlistentry>
<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
calculated as shown in <xref linkend="dbdoclet.50569333_37259"/>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</chapter>

524
Platform/ch_numa.xml
Unescape Escape View File

@ -0,0 +1,524 @@
<?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>
<title>Summary of Extensions to Support NUMA</title>
<para>NUMA platforms to a first level approximation are simply a large
scale Symmetric Multi-Processor. However to tune system performance and to aid
in platform maintenance, the OS needs additional information and mechanisms.
These include:</para>

<itemizedlist>
<listitem>
<para>Associativity -- to determine the platform resource
groupings.</para>
</listitem>
<listitem>
<para>Relative Performance Distances -- to determine the performance
between resources within different groupings.</para>
</listitem>
<listitem>
<para>Performance Monitor -- to provide usage data on the NUMA
fabric.</para>
</listitem>
<listitem>
<para>Dynamic Reconfiguration -- due to such causes as platform upgrade,
reallocation of resources, or a repair of a failure.</para>
</listitem>
</itemizedlist>

<para>There are two NUMA support options: the &#x201C;NUMA&#x201D; option
and its proper subset the &#x201C;Associativity Information&#x201D;
option.</para>
</section>
<section xml:id="dbdoclet.50569346_90086">
<title>NUMA Resource Associativity</title>
<para>Associativity Codes represent the groupings of the various platform
resources into domains of substantially similar mean performance relative to
resources outside of that domain. Resources subsets of a given domain that
exhibit better performance relative to each other than relative to other
resources subsets, are represented as being members of a sub-grouping domain.
Such sub-domain grouping is represented to any level deemed significant by the
platform design. <xref linkend="dbdoclet.50569346_57930"/> presents a simple
system configuration with one possible decomposition into associativity
domains. From the decomposition provided the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> value string for each resource is
enumerated. </para>

<figure xml:id="dbdoclet.50569346_57930">
<title>Example NUMA configuration with
domains and corresponding <emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
values </title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-32.gif" format="GIF" scalefit="1"/>
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-32.gif" format="GIF" scalefit="1" width="100%"/>
</imageobject>
</mediaobject>
</figure>
<para> The OF Device Tree node for each allocable resource
(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="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>
<para>The legal form of the <emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
property is dependent upon the setting of the
<emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
property byte 5 bit 0. The bit value of zero allows the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property string to be sequenced in
priority order; this form is being deprecated for new implementations in favor
of the form indicated by the
<emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
property byte 5 bit 0 having the value of one in which the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property string represents the
strict physical hierarchy of the platform.</para>
<para>When the LPAR option is also implemented, the partition virtual
resources may be mapped onto physical resources with in a very dynamic manor.
Given that the resource mapping to the associativity domain is substantially
consistent, the client program can make use of the associativity information to
on the average optimize performance. If the resource mapping to the
associativity domain is substantially inconsistent, then associativity
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="LoPAR.RTAS"/>).</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569346_19785">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_90086"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> The platform must include the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> in the OF device tree
<emphasis role="bold"><literal>memory</literal></emphasis> node and the nodes of each processor, memory
region, and PCI bridge onto which IOAs may be plugged if the component is
dedicated to the partition. (The device tree node for a component that the
platform intends to virtualize should include an
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property if the associativity
domain information is substantially accurate.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_90086"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA option and SPLPAR
option:</emphasis> In the case that both the NUMA and SPLPAR options are
implemented, Requirement <xref linkend="dbdoclet.50569346_19785"/> is modified
to remove processors from the list of system elements that must include the
respective properties or interfaces described by that requirement. (The
platform is encouraged to provide processor associativity information if it is
substantially accurate.)</para>
</listitem>
</varlistentry>
</variablelist>

<para>The <emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
property contains one or more lists of numbers representing the
resource&#x2019;s platform grouping domains. Each list, starts with a number
representing the domain number of the highest level grouping within which the
platform is capable of supporting direct access. This highest level may be a
NUMA collective or possibly a cluster of machines with direct DMA access.
Successive numbers represent sub-divisions of the previous higher level within
which the expected mean value of the performance relative to outside resources
is substantially similar. Implementations determine the number of levels that
they report, subject to Requirements <xref linkend="dbdoclet.50569346_19785"/>
and <xref linkend="dbdoclet.50569346_29131"/>. The lowest level always being
that of the allocable resource itself. The user of this information is
cautioned not to imply any specific physical/logical significance of the
various intermediate levels.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569346_29131">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_90086"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> Differing levels of resource grouping represented in the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property
must reflect statistically repeatable differences in the expected mean of
measured performance.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_90086"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> The expected mean performance of any resource
of a given type within the same grouping domain represented in the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property relative to
resources outside of that grouping domain must be substantially similar.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The reason that the <emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis>
property may contain
multiple associativity lists is that a resource may be multiply connected into
the platform. This resource then has a different associativity characteristics
relative to its multiple connections. To determine the associativity between
any two resources, the OS scans down the two resources associativity lists in
all pair wise combinations counting how many domains are the same until the
first domain where the two list do not agree. The highest such count is the
associativity between the two resources.</para>
</section>
<section xml:id="sec_numa_perf_distance">
<title>Relative Performance Distance</title>
<para>An OS applies its NUMA tuning techniques based upon associativity and
relative performance distance attributes. As a guide to relative performance
distance, RISC Platforms provide the <emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis>
property. The information in this property represents a first order approximation to points
having associativity and relative performance distance characteristics deemed
to be of significant interest to optimizing client program performance.</para>
<para>The contents of the <emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis>
property is dependent upon the setting of the
<emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
property byte 5 bit 0. The bit value of zero allows the
<emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis> property string
to indicate logical structure points; this form is being deprecated for new
implementations in favor of the form indicated by the
<emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
property byte 5 bit 0 having the value of one in which the
<emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis> property string
represents boundaries between associativity domains presented by the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property containing
&#x201C;near&#x201D; and &#x201C;far&#x201D; resources.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_numa_perf_distance"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> The RTAS OF device tree node must contain the
<emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Form 0</title>
<para>When the <emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
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="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>
<para>The first integer in the <emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis>
property relates the 1 based ordinal in the associativity lists of the platform&#x2019;s
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property associated
with the traditional notion of a symmetric multi-processor within a NUMA
platform. That is the level that represents building blocks of processors and
memory that have the following characteristics:</para>

<itemizedlist>
<listitem>
<para>An OS is likely to view all members having roughly uniform access
characteristics.</para>
</listitem>
<listitem>
<para>Represents the highest level before an OS is likely to notice
major Non-Uniformity of access.</para>
</listitem>
</itemizedlist>

<para>The second integer in the <emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis>
property relates the 1 based ordinal in the associativity lists of the platform&#x2019;s
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property associated
with the traditional notion of a processor group which is sometimes packaged in
a multi-chip module. A processor group has similar characteristics to an SMP,
however, several processor groups get packaged densely within the same physical
enclosure forming an SMP. While the intra processor group accesses are
measurably greater than inter processor group accesses they are a second order
effect. </para>
<para>Subsequent <emphasis>ibm,associativity-reference-points</emphasis> entries are reserved.</para>
</section>
<section xml:id="dbdoclet.50569346_82008">
<title>Form 1</title>
<para>When the <emphasis role="bold"><literal>&#x201C;ibm,architecture-vec-5&#x201D;</literal></emphasis>
property byte 5 bit 0 has the value of one, the
<emphasis role="bold"><literal>&#x201C;ibm,associativity-reference-points&#x201D;</literal></emphasis> property
indicates boundaries between associativity domains presented by the
<emphasis role="bold"><literal>&#x201C;ibm,associativity&#x201D;</literal></emphasis> property containing
&#x201C;near&#x201D; and &#x201C;far&#x201D; resources. The first such boundary
in the list represents the 1 based ordinal in the associativity lists of the
most significant boundary, with subsequent entries indicating progressively
less significant boundaries.</para>
<para><emphasis role="bold">Note</emphasis>: Platforms are encouraged to report
boundaries of actual significance. Thus if a platform has only a single
significant boundary to report, the preferred form of the
<emphasis role="bold"><literal>&#x201C;ibm,associativ&#xAC;ity-reference-points&#x201D;</literal></emphasis> would
contain a single entry. However, providing two or more entries that reference
the same associativity domains provides equivalent information and is a legal
representation.</para>
</section>
</section>
<section xml:id="sec_numa_dr_cross_cec_io">
<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="LoPAR.Error"/>. </para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_numa_dr_cross_cec_io"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> If the platform configuration changes in such a
way that the associativity between an OS image&#x2019;s resources might have
changed, the platform must notify the OS via an event scan or check exception
log.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_numa_max_domains">
<title>Maximum Associativity Domains</title>
<para>Since the number of associativity domains that a platform may exhibit
is not apparent from the associativity properties presented at boot time, the
platform provides the <emphasis role="bold"><literal>&#x201C;ibm,max-associativity-domains&#x201D;</literal></emphasis>
property in the <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the device tree (see
<xref linkend="LoPAR.DeviceTree"/>).</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_numa_max_domains"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the NUMA or Associativity
Information option:</emphasis> The platform must provide the
<emphasis role="bold"><literal>&#x201C;ibm,max-associativity-domains&#x201D;</literal></emphasis> property in
the <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the device tree.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569346_88496">
<title>Platform Resource Reassignment Notification Option (PRRN)</title>
<para>LoPAR platforms that implement the LPAR option are allowed to
transparently reassign the platform resources that are used by a partition. For
instance, if a processor or memory unit is predicted to fail, the platform may
transparently move the processing to an equivalent unused processor or the
memory state to an equivalent unused memory unit. However, reassigning
resources across NUMA boundaries may alter the performance of the partition.
When such reassignment is necessary, the PRRN option provides mechanisms that
inform the supporting OS of changes to the affinity among its platform
resources. It is expected that handling such notifications will involve
significant OS processing, therefore, changing affinity should be avoided, and
when it is necessary to change the affinity of several of the resources owned
by a partition, a single notification after all such changes have occurred is
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="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.
Partitions that are about to be migrated complete/abort any in-process affinity
change processing prior to the migration, and if the target platform does not
support the PRRN option the partition will simply see no more PRRN
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="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
the new affinity information about those resources.</para>
<para>The PRRN <emphasis>event-scan</emphasis> RTAS message contains only
the &#x201C;fixed part&#x201D; with the &#x201C;Type&#x201D; field set to the
value 160 and no Extended Event Log. The four (4) byte Extended Event Log
Length field is repurposed, since no Extended Event Log message is included, to
pass the &#x201C;scope&#x201D; parameter that causes the
<emphasis role="bold"><literal>ibm,update-nodes</literal></emphasis> to return the nodes affected by the specific
resource reassignment.</para>
<para><emphasis role="bold">Requirements:</emphasis></para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_88496"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PRRN Option:</emphasis>
The platform must support the negotiation of the Associativity Information
Option Control Platform Resource Reassignment Notification (Affinity Change)
flag via the <emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis>
interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_88496"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PRRN Option:</emphasis>
If the client code did not claim support for the PRRN option via the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> interface the platform must not
present PRRN events per section <xref
linkend="dbdoclet.50569346_88496"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_88496"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the combination of the PRRN
and Partition Suspension Options:</emphasis> To avoid firmware function
conflicts the client code must complete or abort any PRRN processing prior to
exercising the Partition Suspension option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_88496"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PRRN Option:</emphasis>
The platform must inform the client code of platform resource reassignments via
the <emphasis>event-scan</emphasis> RTAS mechanism with a &#x201C;fixed
part&#x201D; only event return message as presented in <xref
linkend="dbdoclet.50569346_37599"/></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569346_88496"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PRRN Option:</emphasis>
The platform must support the Platform Resource Reassignment scope (negative of
the value contained in bits 32:64 of the RTAS Event Return Format (Fixed Part)
for PRRN events) input parameter to input the
<emphasis role="bold"><literal>ibm,update-nodes</literal></emphasis> RTAS call.</para>
</listitem>
</varlistentry>
</variablelist>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569346_37599">
<title>RTAS Event Return Format (Fixed Part) for PRRN events</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center"/>
<colspec colname="c2" colwidth="70*"/>
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Bit Field Name (bitnumber(s))</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description, Values (Described in <xref linkend="LoPAR.RTAS"/>)</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para> Version (0:7)</para>
</entry>
<entry>
<para> A distinct value used to identify the architectural version of message</para>
</entry>
</row>
<row>
<entry>
<para> Severity (8:10)</para>
</entry>
<entry>
<para> EVENT (1)</para>
</entry>
</row>
<row>
<entry>
<para> RTAS Disposition (11:12)</para>
</entry>
<entry>
<para> FULLY_RECOVERED(0)</para>
</entry>
</row>
<row>
<entry>
<para> Optional_Part_Presence (13)</para>
</entry>
<entry>
<para> NOT_PRESENT (0): The optional Extended Error Log is not present.</para>
</entry>
</row>
<row>
<entry>
<para> Reserved (14:15)</para>
</entry>
<entry>
<para> 0b00</para>
</entry>
</row>
<row>
<entry>
<para> Initiator (16:19)</para>
</entry>
<entry>
<para> HOT PLUG (6) </para>
</entry>
</row>
<row>
<entry>
<para> Target (20:23)</para>
</entry>
<entry>
<para> UNKNOWN (0): Not Applicable</para>
</entry>
</row>
<row>
<entry>
<para> Type (24:31)</para>
</entry>
<entry>
<para> Platform Resource Reassignment (160) &#x2013; includes Change Scope in bits 32:63</para>
</entry>
</row>
<row>
<entry>
<para> Extended Event Log Length / Change Scope (32:63)</para>
</entry>
<entry>
<para> The scope parameter to be input the <emphasis>ibm,update-nodes</emphasis> RTAS call
to retrieve the nodes that were changed by selected &#x201C;Hot Plug&#x201D;
events. </para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</chapter>

148
Platform/ch_platform_intro.xml
Unescape Escape View File

@ -0,0 +1,148 @@
<?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
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
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
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
between the PCI standards.</para>

<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>
</listitem>
<listitem>
<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;
&#x201C;switch,&#x201D; and &#x201C;root complex&#x201D; respectively.</para>
</listitem>
</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
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
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
same, even if the physical topology is different.</para>

<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,
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
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
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
available from third-party industry sources.</para>
<figure xml:id="dbdoclet.50569326_34945">
<title>Typical Desktop Topology</title>
<mediaobject>
<imageobject role="html"><imagedata fileref="figures/PAPR-3.gif" format="GIF" scalefit="1"/></imageobject>
<imageobject role="fo"><imagedata contentdepth="100%" fileref="figures/PAPR-3.gif" format="GIF" scalefit="1" width="100%"/></imageobject>
</mediaobject>
</figure>
<figure xml:id="dbdoclet.50569326_34945.1">
<title>General Platform Topology</title>
<mediaobject>
<imageobject role="html"><imagedata fileref="figures/PAPR-4.gif" format="GIF" scalefit="1"/></imageobject>
<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
at a distance from the main processor enclosure.</para>
</section>
</chapter>

813
Platform/ch_processors_memory.xml
Unescape Escape View File

@ -0,0 +1,813 @@
<?xml version="1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<title>Processor and Memory</title>

<para>The purpose of this chapter is to specify the processor and memory
requirements of this architecture. The processor architecture section addresses
differences between the processors in the PA family as well as their interface
variations and features of note. The memory architecture section addresses
coherency, minimum system memory requirements, memory controller requirements,
and cache requirements.</para>
<section xml:id="dbdoclet.50569329_20555">
<title>Processor Architecture</title>
<para>The Processor Architecture (PA) governs software compatibility at an
instruction set and environment level. However, each processor implementation
has unique characteristics which are described in its user&#x2019;s manual. To
facilitate shrink-wrapped software, this architecture places some limitations
on the variability in processor implementations. Nonetheless, evolution of the
PA and implementations creates a need for both software and hardware developers
to stay current with its progress. The following material highlights areas
deserving special attention and provides pointers to the latest
information.</para>
<section>
<title>Processor Architecture Compliance</title>
<para>The PA is defined in <xref linkend="dbdoclet.50569387_99718"/>.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569329_26424">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_20555"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms must incorporate only processors which comply fully
with <xref linkend="dbdoclet.50569387_99718"/>.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_10712">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_20555"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric Multiprocessor option:</emphasis>
Multiprocessing platforms must use only processors which
implement the processor identification register. </para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_25146">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_20555"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Platforms must incorporate only processors which implement
<emphasis>tlbie</emphasis> and <emphasis>tlbsync</emphasis>, and
<emphasis>slbie</emphasis> and <emphasis>slbia</emphasis> for
64-bit implementations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_20555"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Except where specifically noted otherwise
in <xref linkend="dbdoclet.50569329_37082"/>, platforms must support all
functions specified by the PA.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Hardware and Software Implementation Note:</emphasis> The PA and this
architecture view tlbia
as an optional performance enhancement. Processors need not
implement tlbia. Software that needs to purge the TLB should provide a sequence
of instructions that is functionally equivalent to tlbia and use the content of
the OF device tree to choose the software implementation or the hardware
instruction. See <xref linkend="dbdoclet.50569329_27369"/> for details.</para>
</section>
<section xml:id="dbdoclet.50569329_27369">
<title>PA Processor Differences</title>
<para>A complete understanding of processor differences may be obtained
by studying <xref linkend="dbdoclet.50569387_99718"/> and the user&#x2019;s
manuals for the various processors. </para>
<para>The creators of this architecture cooperate with processor
designers to maintain a list of supported differences, to be used by the OS
instead of the processor
version number (PVN),
enabling execution on future processors. OF communicates these differences via properties of the
<emphasis role="bold"><literal>cpu</literal></emphasis> node of the OF device tree. Examples of OF device
tree properties which support these differences include <emphasis role="bold"><literal>&#x201C;64-bit&#x201D;</literal></emphasis>
and <emphasis role="bold"><literal>&#x201C;performance-monitor&#x201D;</literal></emphasis>. See
<xref linkend="LoPAR.RTAS"/> for a complete listing and more details. </para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569329_14931">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The OS must use the properties of the <emphasis role="bold"><literal>cpu</literal></emphasis>
node of the OF device tree to determine the programming model of the processor
implementation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The OS must provide an execution path
which uses the properties of the <emphasis role="bold"><literal>cpu</literal></emphasis> node of the OF
device. The PVN
is available to the platform aware OS for exceptional cases such as performance
optimization and errata handling.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_26541">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>The OS must
support the 64-bit page table formats defined by
<xref linkend="dbdoclet.50569387_99718"/>. </para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_18405">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Processors which exhibit the
<emphasis role="bold"><literal>&#x201C;64-bit&#x201D;</literal></emphasis> property of the
<emphasis role="bold"><literal>cpu</literal></emphasis> node of the OF device tree must also implement the
&#x201C;bridge architecture,&#x201D; an option in <xref linkend="dbdoclet.50569387_99718"/>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_15696">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Platforms must restrict their choice of processors to those whose
programming models may be described by the properties defined for the
<emphasis role="bold"><literal>cpu</literal></emphasis> node of the OF device tree in
<xref linkend="LoPAR.RTAS"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Platform firmware must initialize the
second and third pages above <emphasis>Base</emphasis> correctly for the
processor in the platform prior to giving control to the OS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para>OS and application software must not
alter the state of the second and third pages above <emphasis>Base</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_27369"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para>Platforms must implement the
<emphasis role="bold"><literal>&#x201C;ibm,platform-hardware-notification&#x201D;</literal></emphasis> property (see
<xref linkend="LoPAR.DeviceTree"/>) and include all PVRs that the platform may
contain.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569329_40499">
<title>64-bit Implementations</title>
<para>Some 64-bit processor implementations will not support the full
virtual address allowed by <xref linkend="dbdoclet.50569387_99718"/>. As a
result, this architecture adds a 64-bit virtual address subset to the PA and
the corresponding <emphasis role="bold"><literal>cpu</literal></emphasis> node property
<emphasis role="bold"><literal>&#x201C;64-bit-virtual-address&#x201D;</literal></emphasis> to OF. </para>
<para>In order for an OS to make use of the increased addressability of
64-bit processor implementations:</para>

<itemizedlist>
<listitem>
<para>The memory subsystem must support the addressing of memory
located at or beyond 4 GB, and</para>
</listitem>
<listitem>
<para>Any system memory located at or beyond 4 GB must be reported via
the OF device tree.</para>
</listitem>
</itemizedlist>

<para>At an abstract level, the effort to support 64-bit architecture in
platforms is modest. The requirements follow.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40499"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>The OS must support the 64-bit virtual
address subset, but may defer support of the full 80-bit virtual address until
such time as it is required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40499"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Firmware must report the
<emphasis role="bold"><literal>&#x201C;64-bit-virtual-address&#x201D;</literal></emphasis>
property for processors which implement the 64-bit virtual address subset.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40499"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>RTAS must be capable of being
instantiated in either a 32-bit or 64-bit mode on a platform with addressable
memory above 4 GB.</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Software Implementation Note:</emphasis> A 64-bit OS need not require 64-bit
client interface services in order to boot. Because of the problems that might
be introduced by dynamically switching between 32-bit and 64-bit modes in OF,
the configuration variable <emphasis role="bold"><literal>64-bit-mode?</literal></emphasis> is provided so
that OF can statically configure itself to the needs of the OS.</para>
</section>
</section>
<section>
<title>Processor Interface Variations</title>
<para>Individual processor interface implementations are described in
their respective user&#x2019;s manuals.</para>
</section>
<section xml:id="dbdoclet.50569329_37082">
<title>PA Features Deserving Comment</title>
<para>Some PA features are optional, and need not be implemented in a
platform. Usage of others may be discouraged due to their potential for poor
performance. The following sections elaborate on the disposition of these
features in regard to compliance with the PA.</para>
<section>
<title>Multiple Scalar Operations</title>
<para>The PA supports multiple scalar operations. The multiple scalar
operations are Load and Store String and Load and Store Multiple.
Due to the long-term performance disadvantage associated with multiple scalar
operations, their use by software is not recommended. </para>
</section>
<section>
<title>External Control Instructions (Optional)</title>
<para>The external control instructions
(eciwx and ecowx) are not supported
by this architecture.</para>
</section>
</section>
<section>
<title><emphasis role="bold"><literal>cpu</literal></emphasis> Node <emphasis role="bold"><literal>&#x201C;Status&#x201D;</literal></emphasis> Property</title>
<para>See <xref linkend="LoPAR.RTAS"/> for the values of the
<emphasis role="bold"><literal>&#x201C;status&#x201D;</literal></emphasis> property of the <emphasis role="bold"><literal>cpu</literal></emphasis>
node.</para>
</section>
<section xml:id="sec_proc_mem_smt">
<title>Multi-Threading Processor Option</title>
<para>Power processors may optionally support multi-threading.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_smt"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Multi-threading
Processor option:</emphasis> The platform must supply one entry in the
<emphasis role="bold"><literal>ibm,ppc-interrupt-server#s</literal></emphasis> property associated with the
processor for each thread that the processor supports.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Refer to <xref linkend="LoPAR.DeviceTree"/> for the definition of
the <emphasis role="bold"><literal>ibm,ppc-interrupt-server#s</literal></emphasis> property.</para>
</section>
</section>
<section xml:id="dbdoclet.50569329_37207">
<title>Memory Architecture</title>
<para>The Memory Architecture of an LoPAR implementation is defined by
<xref linkend="dbdoclet.50569387_99718"/> and
<xref linkend="dbdoclet.50569328_Address-Map"/>, which defines what platform elements
are accessed by each real (physical) system address, as well as the sections
which follow.</para>
<para>The PA allows implementations to incorporate such performance
enhancing features as write-back caching, non-coherent instruction caches,
pipelining, and out-of-order and speculative execution. These features
introduce the concepts of <emphasis>coherency</emphasis> (the apparent order
of storage operations to a single memory location as observed by other
processors and DMA) and <emphasis>consistency</emphasis> (the order of storage
accesses among multiple locations). In most cases, these features are
transparent to software. However, in certain circumstances, OS software
explicitly manages the order and buffering of storage operations. By
selectively eliminating ordering options, either via storage access mode bits
or the introduction of storage barrier instructions, software can force
increasingly restrictive ordering semantics upon its storage operations. Refer
to <xref linkend="dbdoclet.50569387_99718"/> for further details.</para>
<para>PA processor designs usually allow, under certain conditions, for
caching, buffering, combining, and reordering in the platform&#x2019;s memory
and I/O subsystems. The platform&#x2019;s memory subsystem, system
interconnect, and processors, which cooperate through a platform implementation
specific protocol to meet the PA specified memory coherence, consistency, and
caching rules, are said to be within the platform&#x2019;s <emphasis>coherency
domain</emphasis>.</para>
<para><xref linkend="dbdoclet.50569329_30591"/> shows an example system.
The shaded portion is the PA coherency domain. Buses 1 through 3 lie outside
this domain. The figure shows two
I/O subsystems, each interfacing with the host system via a Host Bridge. Notice that
the domain includes portions of the Host Bridges. This symbolizes the role of
the bridge to apply PA semantics to reference streams as they enter or leave
the coherency domain, while implementing the ordering rules of the I/O bus
architecture.</para>
<para>Memory, other than System Memory, is not required to be coherent.
Such memory may include memory in IOAs.</para>
<figure xml:id="dbdoclet.50569329_30591" xreflabel="">
<title>Example System Diagram Showing the PA Coherency Domain</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-15.gif" format="GIF" scalefit="1"/>
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-15.gif" format="GIF" scalefit="1" width="100%"/>
</imageobject>
</mediaobject>
</figure>

<para><emphasis role="bold">Hardware Implementation Note:</emphasis> Components of the platform within the
coherency domain (memory controllers and in-line caches, for example)
collectively implement the PA memory model, including the ordering of
operations. Special care should be given to configurations for which multiple
paths exist between a component that accesses memory and the memory itself, if
accesses for which ordering is required are permitted to use different paths.</para>
<section xml:id="dbdoclet.50569329_19178">
<title>System Memory</title>
<para>System Memory normally consists of dynamic read/write random access
memory which is used for the temporary storage of programs and data being
operated on by the processor(s). A platform usually provides for the expansion
of System Memory via plug-in memory modules and/or memory boards.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_19178"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Platforms must provide at least 128 MB of
System Memory. (Also see <xref linkend="dbdoclet.50569328_Address-Map"/> for
other requirements which apply to memory within the first 32MB of System
Memory.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_19178"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Platforms must support the expansion of
System Memory to 2 GB or more.</para>
</listitem>
</varlistentry>
</variablelist>

<para><emphasis role="bold">Hardware Implementation Note:</emphasis> These requirements are minimum
requirements. Each OS has its own recommended configuration which may be
greater.</para>

<para><emphasis role="bold">Software Implementation Note:</emphasis> System Memory will be described by
the properties of the <emphasis role="bold"><literal>memory</literal></emphasis> node(s) of the OF
device tree.</para>
</section>
<section xml:id="dbdoclet.50569329_40286">
<title>Memory Mapped I/O (MMIO) and DMA Operations</title>
<para>Storage operations which cross the coherency domain boundary are
referred to as Memory Mapped I/O (MMIO) operations if they are initiated within
the coherency domain, and DMA operations
if they are initiated outside the coherency domain
and target storage within it. Accesses with targets outside the coherency
domain are assumed to be made to IOAs. These accesses are considered performed
(or complete) when they complete at the IOA&#x2019;s I/O bus interface.</para>
<para>Bus bridges translate between bus operations on the initiator and
target buses. In some cases, there may not be a one-to-one correspondence
between initiator and target bus transactions. In these cases, the bridge
selects one or a sequence of transactions which most closely matches the
meaning of the transaction on the source bus. See also
<xref linkend="dbdoclet.50569330_13240"/> for more details and the appropriate PCI
specifications.</para>
<para>For MMIO <emphasis>Load</emphasis> and <emphasis>Store</emphasis>
instructions, the software needs to set up the WIMG bits
appropriately to control <emphasis>Load</emphasis> and <emphasis>Store</emphasis> caching,
<emphasis>Store</emphasis> combining, and
speculative <emphasis>Load</emphasis> execution to I/O addresses. This
architecture does not require platform support of caching of MMIO
<emphasis>Load</emphasis> and <emphasis>Store</emphasis> instructions.
See the PA for more information.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569329_61703">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40286"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For MMIO <emphasis>Load</emphasis> and <emphasis>Store</emphasis> instructions,
the hardware outside of the processor must not
introduce any reordering of the MMIO instructions for a processor or processor
thread which would not be allowed by the PA for the instruction stream executed
by the processor or processor thread. </para>
<para><emphasis role="bold">Hardware Implementation Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569329_61703"/> may imply that hardware outside of
the processor cannot reorder MMIO instructions from the same processor or
processor thread, but this depends on the processor implementation. For
example, some processor implementations will not allow multiple
<emphasis>Loads</emphasis> to be issued when those <emphasis>Loads</emphasis> are to
Cache Inhibited and Guarded space (as are MMIO <emphasis>Loads</emphasis> ) or
allow multiple <emphasis>Stores</emphasis> to be issued when those
<emphasis>Stores</emphasis> are to Cache Inhibited and Guarded space (as are MMIO
<emphasis>Stores</emphasis>). In this example, hardware external to the
processors could re-order <emphasis>Load</emphasis> instructions with respect
to other <emphasis>Load</emphasis> instructions or re-order
<emphasis>Store</emphasis> instructions with respect to other <emphasis>Store</emphasis>
instructions since they would not be from the same processor or thread.
However, hardware outside of the processor must still take care not to re-order
<emphasis>Loads</emphasis> with respect to <emphasis>Stores</emphasis> or
vice versa, unless the hardware has access to the entire instruction stream to
see explicit ordering instructions, like eieio. Hardware outside of the
processor includes, but is not limited to, buses, interconnects, bridges, and
switches, and includes hardware inside and outside of the coherency
domain.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40286"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis>(Requirement Number Reserved
For Compatibility)</emphasis></para>
</listitem>
</varlistentry>
</variablelist>

<para>Apart from the ordering disciplines stated in Requirements
<xref linkend="dbdoclet.50569329_61703"/> and, for PCI the ordering of MMIO
<emphasis>Load</emphasis> data return versus buffered DMA data, as defined by
Requirement <xref linkend="dbdoclet.50569330_63508"/>, no other ordering
discipline is guaranteed by the system hardware for <emphasis>Load</emphasis>
and <emphasis>Store</emphasis> instructions performed by a processor to
locations outside the PA coherency domain. Any other ordering discipline, if
necessary, must be enforced by software via programming means.</para>
<para>The elements of a system outside its coherency domain are not
expected to issue explicit PA ordering operations. System hardware must
therefore take appropriate action to impose ordering disciplines on storage
accesses entering the coherency domain. In general, a strong-ordering rule is
enforced on an IOA&#x2019;s accesses to the same location, and write operations
from the same source are completed in a sequentially consistent manner. The
exception to this rule is for the special protocol ordering modifiers that may
exist in certain I/O bus protocols. An example of such a protocol ordering
modifier is the PCI Relaxed Ordering bit<footnote xml:id="pgfId-1015959"><para>The PCI
Relaxed Ordering bit is an optional
implementation, from both the IOA and platform perspective. </para></footnote>,
as indicated in the requirements, below.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40286"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Platforms must guarantee that accesses
entering the PA coherency domain that are from the same IOA and to the same
location are completed in a sequentially consistent manner, except transactions
from PCI-X and PCI Express masters may be reordered when the Relaxed Ordering
bit in the transaction is set, as specified in the
<emphasis><xref linkend="dbdoclet.50569387_26550"/></emphasis> and
<emphasis><xref linkend="dbdoclet.50569387_66784"/></emphasis>. </para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_22857">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40286"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>Platforms must guarantee that multiple write operations entering
the PA coherency domain that are issued by the same IOA are completed in a
sequentially consistent manner, except transactions from PCI-X and PCI Express
masters may be reordered when the Relaxed Ordering bit in the transaction is
set, as specified in the
<emphasis><xref linkend="dbdoclet.50569387_26550"/></emphasis> and
<emphasis><xref linkend="dbdoclet.50569387_66784"/></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_41040">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_40286"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para>Platforms must be designed to present I/O DMA writes to the coherency domain in the order required by
<xref linkend="dbdoclet.50569387_99718"/>, except transactions from PCI-X and PCI
Express masters may be reordered when the Relaxed Ordering bit in the
transaction is set, as specified in the
<emphasis><xref linkend="dbdoclet.50569387_26550"/></emphasis> and
<emphasis><xref linkend="dbdoclet.50569387_66784"/></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Storage Ordering and I/O Interrupts</title>
<para>The conclusion of I/O operations is often communicated to
processors via interrupts. For example, at the end of a DMA operation that
deposits data in the System Memory, the IOA performing the operation might send
an interrupt to the processor. Arrival of the interrupt, however, may be no
guarantee that all the data has actually been deposited; some might be on its
way. The receiving program must not attempt to read the data from the memory
before ensuring that all the data has indeed been deposited. There may be
system and I/O subsystem specific method for guaranteeing this. See <xref
linkend="dbdoclet.50569330_35877"/>.</para>
</section>
<section xml:id="sec_proc_mem_atomic_update">
<title>Atomic Update Model</title>
<para>An update of a memory location by a processor, involving a
<emphasis>Load</emphasis> followed by a <emphasis>Store</emphasis>, can be
considered &#x201C;atomic&#x201D; if there are no intervening
<emphasis>Store</emphasis>s to that location from another processor or mechanism. The PA
provides primitives in the form of Load
And Reserve and Store
Conditional instructions which can be used to determine if the update was
indeed atomic. These primitives can be used to emulate operations such as
&#x201C;atomic read-modify-write&#x201D; and &#x201C;atomic
fetch-and-add.&#x201D; Operation of the atomic update primitives is based on
the concept of &#x201C;Reservation,&#x201D;<footnote xml:id="pgfId-128426"><para>See
Book I and II of <xref linkend="dbdoclet.50569387_99718"/>.</para></footnote>
which is supported in an LoPAR system via the coherence mechanism.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_atomic_update"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis>Load And Reserve</emphasis> and
<emphasis>Store Conditional</emphasis> instructions
must not be assumed to be supported for Write-Through storage.</para>
<para><emphasis role="bold">Software Implementation Note:</emphasis> To emulate an
atomic read-modify-write operation, the instruction pair must access the same
storage location, and the location must have the Memory Coherence Required
attribute.</para>
<para><emphasis role="bold">Hardware Implementation Note:</emphasis> The reservation
protocol is defined in Book II of the <xref linkend="dbdoclet.50569387_99718"/>
for atomic updates to locations in the same coherency domain.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_atomic_update"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The <emphasis>Load And
Reserve</emphasis> and <emphasis>Store Conditional</emphasis> instructions
must not be assumed to be supported for Caching-Inhibited storage.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="sec_proc_mem_memory_controller">
<title>Memory Controllers</title>
<para>A Memory Controller responds to the real (physical) addresses
produced by a processor or a host bridge for accesses to System Memory. It is
responsible for handling the translation from these addresses to the physical
memory modules within its configured domain of control.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_memory_controller"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Memory controller(s) must support the
accessing of System Memory as defined in <xref linkend="dbdoclet.50569328_Address-Map"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_memory_controller"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>Memory controller(s) must be fully initialized and
set to full power mode prior to the transfer of control to the OS. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_memory_controller"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>All allocations of System Memory space
among memory controllers must have been done prior to the transfer of control
to the OS.</para>
</listitem>
</varlistentry>
</variablelist>
<para><emphasis role="bold">Software Implementation Note:</emphasis> Memory controller(s) are described by
properties of the <emphasis role="bold"><literal>memory-controller</literal></emphasis> node(s) of the OF device
tree.</para>
</section>
<section xml:id="dbdoclet.50569329_10945">
<title>Cache Memory</title>
<para>All of the PA processors include some amount of on-chip or
internal cache memory.
This architecture allows for cache memory which is external to the processor
chip, and this external
cache memory forms an extension to internal cache memory. </para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>If a platform implementation elects not
to cache portions of the address map in all external levels of the cache
hierarchy, the result of not doing so must be transparent to the operation of
the software, other than as a difference in performance.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569329_35915">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>All caches must be fully
initialized and enabled, and they must have
accurate state bits prior to the transfer of control to the OS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>If an in-line external
cache is used, it must support one reservation as
defined for the <emphasis>Load And Reserve</emphasis> and
<emphasis>Store Conditional</emphasis> instructions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric
Multiprocessor option:</emphasis> Platforms must implement their cache
hierarchy such that all caches at a given level in the cache hierarchy can be
flushed and disabled before any caches at the next level which may cache the
same data are flushed and disabled (that is, L1 first, then L2, and so
on).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Symmetric
Multiprocessor option:</emphasis> If a cache implements snarfing,
then the cache must be capable of disabling the snarfing during flushing in order to implement
the RTAS <emphasis>stop-self</emphasis> function in an atomic way.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_10945"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para>Software must not depend on being able to
change a cache from copy-back to write-through.</para>
</listitem>
</varlistentry>
</variablelist>

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

<orderedlist>
<listitem>
<para>Each first level cache will be defined via properties of the
<emphasis role="bold"><literal>cpu</literal></emphasis> node(s) of the OF device tree. Each higher level cache will be
defined via properties of the <emphasis role="bold"><literal>l2-cache</literal></emphasis> node(s)
of the OF device tree. See <xref linkend="LoPAR.RTAS"/> for more details.</para>
</listitem>

<listitem>
<para>To ensure proper operation, cache(s) at the same level in the
cache hierarchy should be flushed and disabled before cache(s) at the next
level (that is, L1 first, then L2, and so on).</para>
</listitem>
</orderedlist>

</section>
<section xml:id="sec_proc_mem_memory_info">
<title>Memory Status information</title>
<para>New OF properties are defined to support the identification and
contain the status information on good and bad system memory.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_proc_mem_memory_info"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>Firmware must implement all of the
properties for memory modules, as specified by <xref linkend="LoPAR.DeviceTree"/>,
and any other properties defined by this document which apply to memory modules.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569329_41706">
<title>Reserved Memory</title>
<para>Sections of System Memory may be reserved for usage by OS
extensions, with the restrictions detailed below. Memory nodes marked with the
special value of the <emphasis role="bold"><literal>&#x201C;status&#x201D;</literal></emphasis> property of
&#x201C;reserved&#x201D; is not to be used or altered by the base OS. Several
different ranges of memory may be marked as &#x201C;reserved&#x201D;. If DLPAR
of memory is to be supported and growth is expected, then, an address range
must be unused between these areas in order to allow growth of these areas.
Each area has its own DRC Type (starting at 0, MEM, MEM-1, MEM-2, and so on).
Each area has a current and a maximum size, with the current size being the sum
of the sizes of the populated DRCs for the area and the max being the sum total
of the sizes of all the DRCs for that area. The logical address space allocated
is the size of the sum of the all the areas' maximum sizes. Starting with
logical real address 0, the address areas are allocated in the following order:
OS, DLPAR growth space for OS (if DLPAR is supported), reserved area (if any)
followed by the DLPAR growth space for that reserved area (if DLPAR is
supported), followed by the next reserved space (if any), and so on. The
current memory allocation for each area is allocated contiguously from the
beginning of the area. On a boot or reboot, including hypervisor reboot, if
there is any data to be preserved (that is, the
<emphasis role="bold"><literal>&#x201C;ibm,preserved-storage&#x201D;</literal></emphasis>
property exists in the RTAS
node), then the starting logical real address of each LMB is maintained through
the reboot. The memory in each region can be independently increased or
decreased using DLPAR memory functions, when DLPAR is supported. Changes to the
current memory allocation for an area results in the addition or removal of
memory to the end of the existing memory allocation.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> if the shared memory
regions are not accessed by the programs, and are just used for DMA most of the
time, then the same HPFT hit rate could be achieved with a far lower ration of
HPFT entries to logical storage space.</para>

<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_41706"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reserved Memory option:</emphasis>
Memory nodes marked with the special value of the <emphasis role="bold"><literal>&#x201C;status&#x201D;</literal></emphasis>
property of &#x201C;reserved&#x201D; must not be used or altered by the base OS</para>
<para><emphasis role="bold">Implementation Note:</emphasis> How areas get chosen to
be marked as reserved is beyond the scope of this architecture.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569329_41706"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the Reserved Memory option
with the LRDR option:</emphasis> Each unique memory area that is to be changed
independently via DLPAR must have different DRC Types (for example, MEM, MEM-1,
and so on).</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="dbdoclet.50569329_70628">
<title>Persistent Memory</title>
<para>Selected regions of storage (LMBs) may be optionally preserved
across client program boot cycles. See <xref linkend="dbdoclet.50569327_70628"/> and
"Managing Storage Preservations" in <xref linkend="LoPAR.RTAS"/> specification.</para>
</section>
</section>

</chapter>

4638
Platform/ch_product_topology.xml
View File

File diff suppressed because it is too large Load Diff

373
Platform/ch_smp.xml
Unescape Escape View File

@ -0,0 +1,373 @@
<?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="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>
<listitem>
<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="LoPAR.Error"/></para>
</listitem>
</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
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.
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
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
<xref linkend="dbdoclet.50569346_35960"/>.</para>

<variablelist>
<varlistentry xml:id="dbdoclet.50569340_80907">
<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
SMP-enabled platforms, actively using only one processor. </para>
</listitem>
</varlistentry>
<varlistentry>
<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
option:</emphasis> SMP OSs must support uniprocessor platforms.</para>
</listitem>
</varlistentry>
<varlistentry>
<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="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"
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
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"
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"/>,
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"
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
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"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<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"
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="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"
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
by processor &#x201C;B&#x201D;.</para>
</listitem>
</varlistentry>
</variablelist>

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

<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
<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
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
higher-overhead but more general <emphasis>sync</emphasis> instruction. </para>
</listitem>
</orderedlist>

<para><emphasis role="bold">Hardware Implementation Notes:</emphasis></para>
<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
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
province of the OS and other software.</para>
</listitem>
</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
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
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
processors, but does not exploit them. This process proceeds as follows: </para>

<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
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
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="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
following properties: </para>

<itemizedlist>
<listitem>
<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
value. </para>
</listitem>
<listitem>
<para>After the first attempt, all attempts to read that
register&#x2019;s contents return a non-zero value. </para>
</listitem>
</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
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
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"/>
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
<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
discussed above will be covered.</para>
</listitem>
</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="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
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
configuration.</para>
<para>&#xA0;</para>
</section>
</section>
</chapter>

2624
Platform/ch_system_reqs.xml
View File

File diff suppressed because it is too large Load Diff

BIN
Platform/figures/PAPR-10.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
Platform/figures/PAPR-11.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

BIN
Platform/figures/PAPR-12.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
Platform/figures/PAPR-14.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

BIN
Platform/figures/PAPR-15.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
Platform/figures/PAPR-3.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
Platform/figures/PAPR-32.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
Platform/figures/PAPR-4.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
Platform/figures/PAPR-6.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
Platform/figures/PAPR-7.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
Platform/figures/PAPR-8.gif
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

148
Platform/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-Platform</artifactId>

<packaging>jar</packaging>
<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>LoPAR-Platform</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-Platform</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_Platform</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<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>
<!-- 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>

105
README.md
Unescape Escape View File

@ -0,0 +1,105 @@
# Linux Architecture Reference Specification for OpenPOWER
This repository hold the source for the source for the
Linux on Power Architecture Reference documents. There are
multiple component documents as follows:

* The Platform (../Platform/) document describes the basic
requirements to run Linux on the hardware platform.

* The Device Tree (../DeviceTree/) document describes the
structure and bindings associated with the device tree
definitions for OpenPOWER systems.

* The Error Handing (../ErrorHandling/) document describes
the error reporting and recommended error procedures for the system.

* The run-time services or RTAS (../RTAS/) document describes
the firmware interfaces available to Linux running on the system
and in a VM.

* The Virtualization (../Virtualization/) document describes the
environment by which virtualized OS images are run on the system.

The basis for this document was the
[*Linux on Power Architecture Platform Reference (LoPAR)*](https://openpowerfoundation.org/?resource_lib=linux-on-power-architecture-platform-reference)
Version 1.1, March 2016. It was derived from an IBM document known as the *Power Architecture Platform Reference (PAPR)* Versions 2.7. While much of this
documentation may apply to the IBM PowerVM (LPAR) environment, it will serve as a good base for the OpenPOWER documentation effort as well as support the
more broad IBM Linux on Power community as well.

To build this project, one must ensure that the Docs-Master project has
also been cloned at the same directory level as the Docs-Template project.
This can be accomplished with the following steps:

1. Clone the master documentation project (Docs-Master) using the following command:

```
$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git
```
2. Clone this project (Docs-Template) using the following command:

```
$ git clone https://github.com/OpenPOWERFoundation/Linux-Architecture-Reference.git
```
3. Build the project with these commands:
```
$ cd Linux-Architecture-Reference
$ mvn clean generate-sources
```

The online version of the document can be found in the OpenPOWER Foundation
Document library at [TBD](http://openpowerfoundation.org/?resource_lib=tbd)


## Contributions
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:
```
Signed-off-by: Your Name <your_email@domain.com>
```
By contributing in this way, you agree to the terms as follows:
```
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or

(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or

(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.

(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```

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

111
RTAS/bk_main.xml
Unescape Escape View File

@ -0,0 +1,111 @@
<?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</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.0_pre1</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. It 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>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>

173
RTAS/ch_cmo_def.xml
Unescape Escape View File

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

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569382_58396">
<title>CMO Characteristics Definitions</title>
<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
<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
<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="50*" />
<colspec colname="c2" colwidth="50*" />
<tbody>
<row>
<entry>
<para>Term</para>
</entry>
<entry>
<para>Definition</para>
</entry>
</row>
<row>
<entry>
<para>CMO Page Size</para>
</entry>
<entry>
<para>Page size as determined by the hypervisor. CMO page size is
expressed as the power of 2 of the page size. For example, a 4K
page size is represented by the value of 12 (4K = 2
<emphasis>12</emphasis>).</para>
</entry>
</row>
<row>
<entry>
<para>Primary Paging Service Partition</para>
</entry>
<entry>
<para>The primary paging service partition identifies the primary
VIOS which provides access to paging services and devices for
partitions participating in CMO. The primary paging service
partition value is the partition number of the VIOS.</para>
</entry>
</row>
<row>
<entry>
<para>Secondary Paging Service Partition</para>
</entry>
<entry>
<para>The secondary paging service partition identifies the
secondary VIOS in a redundant Paging Service Partition
configuration. If the hypervisor detects a problem with the
primary VIOS, it fails over to the secondary VIOS. The secondary
paging service partition value is the partition number of the
secondary VIOS.</para>
</entry>
</row>
</tbody>
</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
<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
value of the characteristic corresponding to the key word is the decimal
number that corresponds to the numeric characters in the value part of the
key word, value pair.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569382_70763">
<title>CMO Characteristics</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<tbody>
<row>
<entry>
<para>Characteristics</para>
</entry>
<entry>
<para>Key Word</para>
</entry>
<entry>
<para>Values</para>
</entry>
<entry>
<para>Notes</para>
</entry>
</row>
<row>
<entry>
<para>CMO Page Size</para>
</entry>
<entry>
<para>CMOPageSize</para>
</entry>
<entry>
<para>1 - 64</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Primary Paging Service Partition</para>
</entry>
<entry>
<para>PrPSP</para>
</entry>
<entry>
<para>-1 through N</para>
</entry>
<entry morerows="1">
<para>Set to -1 when the partition is not in CMO mode (i.e. is a
dedicated memory partition)</para>
</entry>
</row>
<row>
<entry>
<para>Secondary Paging Service Partition</para>
</entry>
<entry>
<para>SecPSP</para>
</entry>
<entry>
<para>-1 through N</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</chapter>

1272
RTAS/ch_error_codes.xml
View File

File diff suppressed because it is too large Load Diff

4072
RTAS/ch_firmware_dump.xml
View File

File diff suppressed because it is too large Load Diff

24715
RTAS/ch_rtas_call_defn.xml
View File

File diff suppressed because it is too large Load Diff

2560
RTAS/ch_rtas_environment.xml
View File

File diff suppressed because it is too large Load Diff

76
RTAS/ch_rtas_introduction.xml
Unescape Escape View File

@ -0,0 +1,76 @@
<?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="dbdoclet.50569337_66258">
<title>Introduction</title>
<para>The Run-Time Abstraction Service (RTAS) functions are provided by
LoPAR platforms to insulate the OS from having to know about and
manipulate a number of key platform hardware functions which ordinarily
require platform-dependent code. The OS calls RTAS functions rather than
manipulating hardware registers directly, reducing the need for platform
tailoring by the OS. This method of abstracting access to these platform
functions also permits hardware designers considerable flexibility in
hardware implementation. Since RTAS is provided by the platform developer,
this approach places the responsibility for supporting the platform
hardware design with the platform developer, not the OS developer. This
permits a degree of independence between the schedules of hardware and
software and reduces the release and test requirements for the OS, since it
can be tested to conform to the RTAS interface and not to every specific
hardware implementation. See
<xref linkend="dbdoclet.50569332_20008"/>
for a list of all RTAS calls, and
which ones are required based on which LoPAR options that are implemented
in the platform.</para>
<para>In order for platforms to achieve this separation of OS code from
hardware implementation dependencies, RTAS defines an interface between the
platform and the OS that provides control of some of the common devices
found on all platforms. RTAS is a system programming interface that is
realized, on a specific platform, by an RTAS implementation. The RTAS
implementation provides the platform specific processing of the common
components. RTAS limits itself to the run-time control of non-I/O,
typically system board-resident, hardware features. Traditionally, features
such as these have been implemented differently on different platforms. The
different implementations have required much effort and platform-dependent
code in the OS. RTAS permits the OS to operate over a much wider range of
platforms without specialized code for each platform.</para>
<para>In general, the OS should not access RTAS resources directly. It
should call RTAS to control the resource.</para>
<para>OS drivers are necessary to provide device specific processing for
IOAs.</para>
<para>The role of RTAS versus OF is very important to understand. OF and
RTAS are both platform-specific software, and both are tailored by the
platform developer to manipulate the specific platform hardware. However,
RTAS is intended to be present during the execution of the OS, and to be
called by the OS to access platform hardware features on behalf of the OS,
whereas OF need not be present when the OS is running. This frees
OF&#8217;s memory to be used by applications. RTAS is small enough to
painlessly coexist with the OS and applications.</para>
<para>This document uses the term RTAS to refer both to the architected RTAS
interface and to an RTAS implementation.</para>
</chapter>

148
RTAS/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-RTAS</artifactId>

<packaging>jar</packaging>
<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>LoPAR-RTAS</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-RTAS</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_RTAS</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>LoPAR_RTAS</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>

5952
RTAS/sec_rtas_get_indices.xml
View File

File diff suppressed because it is too large Load Diff

284
Virtualization/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>

1282
Virtualization/app_glossary.xml
View File

File diff suppressed because it is too large Load Diff

117
Virtualization/bk_main.xml
Unescape Escape View File

@ -0,0 +1,117 @@
<?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>Virtualization</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</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 2.0_pre1</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 for the base Platform hardware associated with an OpenPOWER Systems.
The base content for this document were contributed to the OpenPOWER Foundation in the
<citetitle>IBM Linux on Power Architecture Platform Reference (LoPAPR) Draft</citetitle>
document. It 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>2017-05-18</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 14 (Logical Partitioning Option), Chapter 13 (Dynamic Reconfiguration
Option), Chapter 17 (Virtualized Input/Output), Appendix A (SPLPAR Characteristics
Definitions), Appendix D (A Protocol for a Virtual TTY Interface), Appendix E
(A Protocol for VSCSI Communications), Appendix F (A Protocol for VMC Communications),
Appendix J (Platform Dependent hcalls), and Appendix K (A Protocol for VNIC Communications)</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_lpar_option.xml"/>
<xi:include href="ch_platform_hcalls.xml"/>
<xi:include href="ch_splpar.xml"/>
<xi:include href="ch_dynamic_reconfig.xml"/>
<xi:include href="ch_virtual_io.xml"/>
<xi:include href="ch_virtual_tty.xml"/>
<xi:include href="ch_virtual_scsi.xml"/>
<xi:include href="ch_virtual_nic.xml"/>
<xi:include href="ch_vmc_comm.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>

4314
Virtualization/ch_dynamic_reconfig.xml
View File

File diff suppressed because it is too large Load Diff

18584
Virtualization/ch_lpar_option.xml
View File

File diff suppressed because it is too large Load Diff

617
Virtualization/ch_platform_hcalls.xml
Unescape Escape View File

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

<para>This chapter defines the set of hypervisor calls (hcall()s) that are
platform dependent. The existence and/or implementation of the hcall() can
vary between firmware releases and between hardware platforms.</para>
<section>
<title>hcall()s Supported by Firmware Release &amp; Hardware
Platform</title>
<para>
<xref linkend="dbdoclet.50569383_56867" /> is a list of platform specific
hcall()s, which will be described in this chapter.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569383_56867">
<title>Platform Dependent hcall()s Supported by Release and
Hardware Platform</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="40*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<thead>
<row>
<entry>
<para><emphasis role="bold">Function Name/Section</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Hypervisor Call Function Token</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Firmware Releases Supported</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Hardware Platform Supported</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>0xF000-0xF07C</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>H_GetPerformanceCounterInfo /
<xref linkend="dbdoclet.50569383_65658" xrefstyle="select: labelnumber" /></para>
</entry>
<entry>
<para>0xF080</para>
</entry>
<entry>
<para>eFW 3.5 and later</para>
</entry>
<entry>
<para>Power 6 and later</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Supported hcall()s</title>
<section xml:id="dbdoclet.50569383_65658">
<title>H_GetPerformanceCounterInfo (0xF080)</title>
<para>This call returns information about the performance of selectable
performance counters maintained by the hardware or from data collected by
the Hypervisor.</para>

<simplesect>
<title>Syntax:</title>

<programlisting><![CDATA[int64 /* H_Success, H_Privilege, H_Authority */
/* H_Hardware, H_Not_Available */
hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */
uint64 size, /* Size of getPerformanceCounterInfoParms */
getPerformanceCounterInfoParms* ); /* Requested/Response data */]]></programlisting>

</simplesect>

<simplesect>
<title>Parameters:</title>

<itemizedlist>
<listitem>
<para>size &#8211; size of the getPerformanceCounterInfoParms</para>
</listitem>
<listitem>
<para>getPerformanceCounterInfoParms &#8211; parameter list indicating
which performance counter information to retrieve.
<xref linkend="dbdoclet.50569383_34010" /></para>
</listitem>
</itemizedlist>
</simplesect>

<simplesect>
<title>Semantics:</title>

<itemizedlist>
<listitem>
<para>Validate the getPerformanceInfoParms is accessible, else
H_Privilege.</para>
</listitem>
<listitem>
<para>Validate the size and contents of getPerformanceCounterInfoParms,
else H_Parameter.</para>
</listitem>
<listitem>
<para>Validate information is available for the firmware level and
platform, else H_Not_Available.</para>
</listitem>
<listitem>
<para>Validate partition is permitted to retrieve performance
information, else H_Authority.</para>
</listitem>
<listitem>
<para>Copy requested performance counters into getPerformanceInfoParms
and return H_Success.</para>
</listitem>
</itemizedlist>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569383_34010">
<title>Performance_Counter_Info_Parms struct</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="45*" align="center" />
<thead>
<row>
<entry align="center">
<para><emphasis role="bold">Member Name</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Member Type</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">IN/OUT</emphasis></para>
</entry>
<entry align="center">
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Requested_Information</para>
</entry>
<entry>
<para>uint_32</para>
</entry>
<entry>
<para>INPUT</para>
</entry>
<entry>
<para>See
<xref linkend="dbdoclet.50569383_64760" /></para>
</entry>
</row>
<row>
<entry>
<para>starting_index</para>
</entry>
<entry>
<para>int_32</para>
</entry>
<entry>
<para>BOTH</para>
</entry>
<entry>
<para>At input, the partition id of the first
processor/partition to retrieve performance metrics. If -1 is
specified for this parameter, only information for the current
processor/partition is returned.</para>
<para>At output, the actual first processor/partition id that
was found.</para>
</entry>
</row>
<row>
<entry>
<para>returned_values</para>
</entry>
<entry>
<para>uint_32</para>
</entry>
<entry>
<para>OUTPUT</para>
</entry>
<entry>
<para>Number of lists of counters returned</para>
</entry>
</row>
<row>
<entry>
<para>reserved</para>
</entry>
<entry>
<para>uint_32</para>
</entry>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>Alignment</para>
</entry>
</row>
<row>
<entry>
<para>reserved</para>
</entry>
<entry>
<para>uint_64[2]</para>
</entry>
<entry>
<para>N/A</para>
</entry>
<entry>
<para>Alignment</para>
</entry>
</row>
<row>
<entry>
<para>counter_value</para>
</entry>
<entry>
<para>perf_data</para>
</entry>
<entry>
<para>BOTH</para>
</entry>
<entry>
<para>Array of counters values</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The possible values for Requested_Information are as shown in
<xref linkend="dbdoclet.50569383_64760" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569383_64760">
<title>Performance Counter Info Requested_Information
Values</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="55*" />
<thead>
<row>
<entry align="center">
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Dispatch_PURR_by_processor</para>
</entry>
<entry>
<para>0x0000 0010</para>
</entry>
<entry>
<para>The value for the counter_value is a list of values per
physical processor as follows:</para>
<itemizedlist>
<listitem>
<para>uint64 processor time (in PURR cycles) that the processor
was running work on behalf of partitions since the boot of the
CEC</para>
</listitem>
<listitem>
<para>uint32 hardware processor id</para>
</listitem>
<listitem>
<para>uint16 owning partition id (0xFFFF is shared or
unowned)</para>
</listitem>
<listitem>
<para>uint8 processor state (0x01-Not Installed, 0x02-Guarded
Off, 0x03-Unlicensed, 0x04-Shared, 0x05-Borrowed,
0x06-Dedicated)</para>
</listitem>
<listitem>
<para>uint8[1] reserved</para>
</listitem>
<listitem>
<para>uint32 hardware chip id (a value of -1 will be returned
for Not Installed processors)</para>
</listitem>
<listitem>
<para>uint32 hardware module id</para>
</listitem>
<listitem>
<para>uint32 primary affinity domain</para>
</listitem>
<listitem>
<para>uint32 secondary affinity domain</para>
</listitem>
<listitem>
<para>uint32 processor version (a value of -1 will be returned
for Not Installed processors)</para>
</listitem>
<listitem>
<para>uint16 logical processor index</para>
</listitem>
<listitem>
<para>uint8[10] reserved</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Entitled_capped<?linebreak?>
_uncapped_donated<?linebreak?>
_idle_PURR<?linebreak?>
_by_partition</para>
</entry>
<entry>
<para>0x0000 0020</para>
</entry>
<entry>
<para>The value for the counter_value is a list of uint64
values as follows:</para>
<para>Partition id</para>
<itemizedlist>
<listitem>
<para>Hypervisor collected PURR cycles that the partition was
entitled to consume since the boot of the CEC (or partition
creation).</para>
</listitem>
<listitem>
<para>Hypervisor collected PURR cycles that the partition
consumed as capped cycles since boot of the CEC (or partition
creation). For a dedicated partition, all cycles consumed will
be reported as capped cycles. For shared, these are the capped
(entitled) cycles consumed by the partition.</para>
</listitem>
<listitem>
<para>Hypervisor collected PURR cycles that the partition
consumed as uncapped shared partition cycles since boot of the
CEC (or partition creation).</para>
</listitem>
<listitem>
<para>Hypervisor collected PURR cycles that were donated from a
dedicated partition to uncapped partitions since boot of the
CEC (or partition creation).</para>
</listitem>
<listitem>
<para>Partition collected PURR cycles that the partition
considers as idle cycles. These cycles can be subtracted from
the total cycles consumed to calculate the partition&#8217;s
view of utilization. Note that not all operating system
versions will report this value.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Run_instructions<?linebreak?>
_run_cycles<?linebreak?>
_by_partition</para>
</entry>
<entry>
<para>0x0000 0030</para>
</entry>
<entry>
<para>The value for the counter_value is a list of uint64
values as follows:</para>
<itemizedlist>
<listitem>
<para>Partition id</para>
</listitem>
<listitem>
<para>Hypervisor collected instructions completed while the run
latch is set since boot of the CEC (or partition creation).
Note that this value will be zero on processors versions that
do not provide the ability to collect this information.</para>
</listitem>
<listitem>
<para>Hypervisor collected cycles while the run latch is set
since boot of the CEC (or partition creation). Note that this
value will be zero on processors versions that do not provide
the ability to collect this information.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>System_performance<?linebreak?>
_capabilities</para>
</entry>
<entry>
<para>0x00000040</para>
</entry>
<entry>
<para>The value for the counter_value is a list of values for
the requesting partition as follows:</para>
<itemizedlist>
<listitem>
<para>uint8 Is partition allowed to get performance data for
other partitions (boolean).</para>
</listitem>
<listitem>
<para>uint8[15] Reserved</para>
</listitem>
<listitem>
<para><emphasis role="bold">Note:</emphasis> This request can only be issued by a partition to
obtain data about itself (i.e. starting_index must always be
-1) H_NOT_AVAILABLE will be returned otherwise.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Processor_bus_utilization_ABC<?linebreak?>
_links</para>
</entry>
<entry>
<para>0x00000050</para>
</entry>
<entry>
<para>The value for the counter_value is a list of values per
physical chip as follows:</para>
<itemizedlist>
<listitem>
<para>uint32 hardware chip id</para>
</listitem>
<listitem>
<para>uint32[3] RESERVED</para>
</listitem>
<listitem>
<para>uint64 idle cycles for A link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for A link was
collected</para>
</listitem>
<listitem>
<para>uint64 idle cycles for B link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for B link was
collected</para>
</listitem>
<listitem>
<para>uint64 idle cycles for C link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for C link was
collected</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Processor_bus_utilization_WXYZ<?linebreak?>
_links</para>
</entry>
<entry>
<para>0x00000060</para>
</entry>
<entry>
<para>The value for the counter_value is a list of values per
physical chip as follows:</para>
<itemizedlist>
<listitem>
<para>uint32 hardware chip id</para>
</listitem>
<listitem>
<para>uint32[3] RESERVED</para>
</listitem>
<listitem>
<para>uint64 idle cycles for W link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for W link was
collected</para>
</listitem>
<listitem>
<para>uint64 idle cycles for X link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for X link was
collected</para>
</listitem>
<listitem>
<para>uint64 idle cycles for Y link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for Y link was
collected</para>
</listitem>
<listitem>
<para>uint64 idle cycles for Z link</para>
</listitem>
<listitem>
<para>uint64 time value (in cycles) data for Z link was
collected</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para>Set MMCRH<?linebreak?>
(LAB ONLY)</para>
</entry>
<entry>
<para>0x8000 1000</para>
</entry>
<entry>
<para>At input, counter_value is a single value with what to
set the Performance Monitor Mode Control Register H to:</para>
<itemizedlist>
<listitem>
<para>uint64 value to set MMCRH to in all processors</para>
</listitem>
</itemizedlist>
<para>There will be no output for this function other than
errors.</para>
<para>
<emphasis role="bold">Note 1:</emphasis> A passed value of (-1) will mean
that collection of these values should be disabled.</para>
<para>
<emphasis role="bole">Note 2:</emphasis> Whenever this value is changed, the
programmable counters (HPMC1 &amp; HPMC2) will be reset in the
next collection cycle.</para>
</entry>
</row>
<row>
<entry>
<para>Retrieve HPMCx<?linebreak?>
(LAB ONLY)</para>
</entry>
<entry>
<para>0x8000 2000</para>
</entry>
<entry>
<para>The value for the counter_value is a list of values per
physical processor as follows:</para>
<itemizedlist>
<listitem>
<para>uint32 hardware processor id</para>
</listitem>
<listitem>
<para>uint32 reserved</para>
</listitem>
<listitem>
<para>uint64 current value of MMCRH for this processor</para>
</listitem>
<listitem>
<para>uint64 elapsed timebase value in cycles since current
MMCRH was set</para>
</listitem>
<listitem>
<para>uint64 value for HPMC1 since current MMCRH was set</para>
</listitem>
<listitem>
<para>uint64 value for HPMC2 since current MMCRH was set</para>
</listitem>
<listitem>
<para>uint64 value for HPMC3 since current MMCRH was set</para>
</listitem>
<listitem>
<para>uint64 current value for HPMC3</para>
</listitem>
<listitem>
<para>uint64 value for HPMC4 since current MMCRH was set</para>
</listitem>
<listitem>
<para>uint64 current value for HPMC4</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</simplesect>
</section>
</section>
</chapter>

535
Virtualization/ch_splpar.xml
Unescape Escape View File

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

<para>This chapter defines the string that is returned by the
ibm,get-system-parameter RTAS call when the parameter token value of 20
(SPLPAR Characteristics) is specified on the ibm,get-system-parameter RTAS
call as per <xref linkend="LoPAR.RTAS" />.</para>
</section>
<section>
<title>SPLPAR Terms</title>
<para>The LoPAR Shared Processor Logical Partition option (SPLPAR) defines
many terms as presented in
<xref linkend="dbdoclet.50569367_35778" />.</para>

<table frame="all" pgwide="1" xml:id="dbdoclet.50569367_35778">
<title>SPLPAR Terms</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center"/>
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Term</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Definition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Bound Threads</para>
</entry>
<entry>
<para>For virtual processor dispatches, if the hypervisor always
dispatches a set of virtual threads together on a physical
processor, the threads are said to be bound. This allows an
operating system to make scheduling decisions based on cache
affinity and work load. A change in this characteristic takes
effect on the next reboot of the partition.</para>
</entry>
</row>
<row>
<entry>
<para>Capacity Increment</para>
</entry>
<entry>
<para>This defines the delta by which the entitled capacity of a
partition can be incremented or decremented by DLPAR/WLM. The
capacity increment is expressed as a percentage of a physical
processor. A change in the capacity increment takes effect on the
next reboot of the partition.</para>
</entry>
</row>
<row>
<entry>
<para>Desired Entitled Capacity</para>
</entry>
<entry>
<para>The desired entitled capacity set by the system
administrator in the partition definition. The desired entitled
capacity is expressed as a percentage of a physical processor.
The desired entitled capacity can change without a reboot of the
partition. The entitled capacity that the partition is currently
using may differ from the desired entitled capacity because of
WLM actions or failed system processors.</para>
</entry>
</row>
<row>
<entry>
<para>Desired Memory</para>
</entry>
<entry>
<para>The desired memory set by the system administrator in the
partition definition. The desired memory is expressed in MB of
storage. The desired memory can change without a reboot of the
partition. The desired memory that the partition is currently
using may differ from the desired memory because of WLM actions
or because of failed system memory.</para>
</entry>
</row>
<row>
<entry>
<para>Desired Number of Processors</para>
</entry>
<entry>
<para>The desired number of virtual processors set by the system
administrator in the partition definition. The desired number of
processors can change without a reboot of the partition. The
number of processors that the partition is currently using may
differ from the desired number of processors because of WLM
actions or because of failed system processors.</para>
</entry>
</row>
<row>
<entry>
<para>Desired Variable Capacity Weight</para>
</entry>
<entry>
<para>The desired variable capacity weight set by the system
administrator in the partition definition. The desired variable
capacity weight is a number between 0 and 255. The desired
variable capacity weight can change without a reboot of the
partition. The variable capacity weight that the partition is
currently using may differ from the desired variable capacity
because of WLM actions.</para>
</entry>
</row>
<row>
<entry>
<para>Dispatch Wheel Rotation Period</para>
</entry>
<entry>
<para>The duration of the hypervisor&#8217;s scheduling window.
The time over which the entitled capacity of a virtual processor
has to be utilized by the partition. At the start of a dispatch
wheel rotation period, each virtual processor is eligible for CPU
time corresponding to its entitled capacity. If the entire
entitled capacity of a virtual processor is not utilized during a
dispatch wheel rotation period, the unused entitled capacity is
lost. The dispatch wheel rotation period is expressed as N number
of time base ticks. The dispatch wheel duration of a partition
with a capacity increment of 100 is 0. A change in the dispatch
wheel rotation period takes effect on the next reboot of the
partition.</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Entitled Capacity</para>
</entry>
<entry>
<para>The minimum entitled capacity that is needed to power on
the partition. The capacity is expressed as a percentage of a
physical processor. The minimum entitled capacity is set by the
system administrator in the partition definition. DLPAR cannot
take the entitled capacity below the minimum entitled capacity. A
change in the minimum entitled capacity takes effect on the next
reboot of the partition. A partition can give up its entitled
capacity to be below the minimum entitled capacity.</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Entitled Capacity per Virtual Processor</para>
</entry>
<entry>
<para>The minimum entitled capacity that the platform requires
for a virtual processor of any partition on the platform. The
minimum virtual per virtual processor is enforced by the HMC in
the partition definition and by the hypervisor for H_SET_PPP (
<xref linkend="dbdoclet.50569344_14689" />). A change in the
minimum entitled capacity per virtual processor takes effect on
the next reboot of the partition.</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Memory</para>
</entry>
<entry>
<para>The minimum amount of main store that is needed to power on
the partition. Minimum memory is expressed in MB of storage. The
minimum memory is set by the system administrator in the
partition definition. DLPAR cannot take the partition memory
below the minimum memory. A change in the minimum memory takes
effect on the next reboot of the partition. A partition can
always give up its memory to go below the minimum memory.</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Number of Processors</para>
</entry>
<entry>
<para>The minimum number of virtual processors that are needed to
start the partition. The minimum number of virtual processors is
set by the system administrator in the partition definition.
DLPAR cannot take the number of virtual processors below the
minimum number of processors. A change in the minimum number of
processors takes effect on the next reboot of the partition. A
partition can always give up its virtual processors to go below
the minimum number of processors.</para>
</entry>
</row>
<row>
<entry>
<para>Maximum Entitled Capacity</para>
</entry>
<entry>
<para>The maximum entitled capacity currently that can be
assigned to the partition through DLPAR/WLM. The capacity is
expressed as a percentage of a physical processor. The Maximum
entitled capacity is set up by the system administrator in the
partition definition. A change in the maximum entitled capacity
maximum takes effect on the next reboot of the partition.</para>
</entry>
</row>
<row>
<entry>
<para>Maximum Platform Processors</para>
</entry>
<entry>
<para>The maximum number of processors that can be active on the
platform. A change in the maximum platform processors takes
effect on the next reboot of the partition.</para>
</entry>
</row>
<row>
<entry>
<para>Dedicated Donate Mode</para>
</entry>
<entry>
<para>For a partition with a capacity increment of 100, the
platform uses a dedicated CPU to actualize a virtual processor of
the partition. For such a partition, the platform can increase
the capacity of the shared processor pool by utilizing the unused
processor capacity of the partition. If the platform supports the
dedicated donate function, it can be enabled by the system
administrator in the partition definition. The value of this
characteristic can change without a reboot of the
partition.</para>
</entry>
</row>
<row>
<entry>
<para>Thread</para>
</entry>
<entry>
<para>A multi threaded processor may have multiple contexts
executing concurrently. Each of them is called a thread. From a
software viewpoint, a thread is an independent executing unit.
Threads on a processor share some of the architected and
unarchitected resources of a physical processor.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Key Words And Values</title>
<para>Table
<xref linkend="dbdoclet.50569367_78034" /> 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 20 (SPLPAR characteristics) is
specified on the ibm,get-system-parameter 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 value of the
characteristic corresponding to the key word is the decimal number that
corresponds to the numeric characters in the value part of the key word,
value pair.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569367_78034">
<title>SPLPAR Characteristics</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="4">
<colspec colname="c1" colwidth="35*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Characteristics</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Key Word</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Notes</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Bound Threads</para>
</entry>
<entry>
<para>BoundThrds</para>
</entry>
<entry>
<para>0,1</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>Capacity Increment</para>
</entry>
<entry>
<para>CapInc</para>
</entry>
<entry>
<para>1 through 100</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Dispatch Wheel Rotation Period</para>
</entry>
<entry>
<para>DisWheRotPer</para>
</entry>
<entry>
<para>1 through N</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Entitled Capacity</para>
</entry>
<entry>
<para>MinEntCap</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Entitled Capacity per Virtual Processor</para>
</entry>
<entry>
<para>MinEntCapPerVP</para>
</entry>
<entry>
<para>1 through 100</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Memory</para>
</entry>
<entry>
<para>MinMem</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Minimum Number of Processors</para>
</entry>
<entry>
<para>MinProcs</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Maximum Entitled Capacity</para>
</entry>
<entry>
<para>MaxEntCap</para>
</entry>
<entry>
<para>1 through N</para>
</entry>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>Maximum Platform Processors</para>
</entry>
<entry>
<para>MaxPlatProcs</para>
</entry>
<entry>
<para>1 through N</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Desired Entitled Capacity</para>
</entry>
<entry>
<para>DesEntCap</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>Desired Memory</para>
</entry>
<entry>
<para>DesMem</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>Desired Number of Processors</para>
</entry>
<entry>
<para>DesProcs</para>
</entry>
<entry>
<para>0 through N</para>
</entry>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>Desired Variable Capacity Weight</para>
</entry>
<entry>
<para>DesVarCapWt</para>
</entry>
<entry>
<para>0 through 255</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Dedicated Donate Mode</para>
</entry>
<entry>
<para>DedDonMode</para>
</entry>
<entry>
<para>0,1</para>
</entry>
<entry>
<para>7</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para><emphasis role="bold">Notes:</emphasis>
<orderedlist>
<listitem>
<para>0=Threads are not bound, 1=Threads are bound.</para>
</listitem>

<listitem>
<para>The maximum numeric value of Minimum Entitled Capacity is the
number of processors on the platform multiplied by 100.</para>
</listitem>

<listitem>
<para>The maximum numeric value of Maximum Entitled Capacity is the
number of processors on the platform multiplied by 100.</para>
</listitem>

<listitem>
<para>The numeric value of Desired Entitled Capacity is greater or equal
than the numeric value of the Minimum Entitled Capacity and less than or
equal to the numeric value of the Maximum Entitled Capacity.</para>
</listitem>

<listitem>
<para>The numeric value of Desired Memory is greater or equal than the
numeric value of the Minimum Memory and less than or equal to the maximum
memory set by the system administrator in the partition profile.</para>
</listitem>

<listitem>
<para>The numeric value of Desired Number of Processors is greater or
equal than the numeric value of the Minimum Number of Processors and less
than or equal to the maximum number of virtual processors set by the system
administrator in the partition profile.</para>
</listitem>

<listitem>
<para>0=Dedicated Donate Mode is disabled, 1=Dedicated Donate Mode is
enabled.</para>
</listitem>
</orderedlist>
</para>
</section>
</chapter>

14520
Virtualization/ch_virtual_io.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