systemsoftware
/
Linux-Architecture-Reference
35
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
papr_2.9+
papr_2.7
lopar-2.9
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a7e8c94fe1'
${ noResults }
Linux-Architecture-Reference/LoPAR/ch_dynamic_reconfig.xml

4477 lines
216 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569342_75822">
<title>Dynamic Reconfiguration (DR) Architecture</title>
<para>Dynamic Reconfiguration (DR) is the capability of a system to adapt to
changes in the hardware/firmware physical or logical configuration, and to be
able to use the new configuration, all without having to turn the platform
power off or restart the OS. This section will define the requirements for
systems that support DR operations.</para>
<section xml:id="dbdoclet.50569342_51213">
<title>DR Architecture Structure</title>
<para>
<xref linkend="dbdoclet.50569342_22277" /> shows the relationship of the DR
architecture with LoPAR and the relationship of the individual DR pieces
with the base DR architecture. Each specific DR option (for example, PCI
Hot Plug) will have a piece that sits on top of the base DR option. The
base DR option is the set of requirements that will be implemented by all
DR platforms and that will be utilized by the OS that supports any of the
specific DR options. The specific DR options will call out the base DR
option requirements as being required. Therefore, in the figure, any
specific DR option is really that specific DR option piece plus the base DR
option. The base DR option is not a stand-alone option; a platform which
supports the base DR option without one or more of the specific DR option
pieces that sit on top of it, has not implemented the DR architecture to a
level that will provide any DR function to the user. Likewise, a DR entity
will meet the requirements of at least one of the specific DR options, or
else software is not required to support it as a DR entity. Thus, the base
DR option is the common building block and structure upon which all other
specific DR options are built.</para>
<para>DR operations can be physical or logical. Currently the only physical
DR entities are PCI Hot Plug. That is, the OS only has control over the
physical DR operations on PCI IOAs. The current direction for hot plug of
other DR entities is to do the physical hot plug (power up/down, control of
service indicators, etc.) via the HMC and to bring the entity into usage by
an OS via logical DR operations (Logical Resource DR -- LRDR). The PCI Hot
Plug DR option can be found in
<xref linkend="dbdoclet.50569342_47470" />. The Logical Resource Dynamic
Reconfiguration option can be found in
<xref linkend="dbdoclet.50569342_75053" />. It is expected that as time
goes on, the base DR option may be expanded upon by addition of other DR
options.</para>
<figure xml:id="dbdoclet.50569342_22277">
<title>DR Architecture Structure</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-18.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-18.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="dbdoclet.50569342_32129">
<title>Definitions Used in DR</title>
<table frame="all" pgwide="1">
<title>DR Definitions</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<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>Base Dynamic Reconfiguration (DR) option</para>
</entry>
<entry>
<para>The base on which all of the specific DR options are built.
Specific DR options include, for example, the PCI Hot Plug DR
option, processor card DR option, etc. These specific DR options
each include the requirement that all the base DR option
requirements be met. See
<xref linkend="dbdoclet.50569342_51213" /> for more information
about the structure of the DR architecture pieces.</para>
</entry>
</row>
<row>
<entry>
<para>Dynamic Reconfiguration (DR)</para>
</entry>
<entry>
<para>The capability of a system to adapt to changes in the
hardware/firmware configuration with the power on and the OS
operating, and to be able to use the new configuration. This is a
piece of the High Availability puzzle, but only one of the
pieces.</para>
<para>Addition, removal, and replacement may, in general, be done
with the power on or off on the connector into which the entity
is being added or removed. For the PCI Hot Plug option, the power
to the slot is turned off and the logic signals are electrically
isolated from the connector during the plug or unplug
operation.</para>
</entry>
</row>
<row>
<entry>
<para>Depth First</para>
</entry>
<entry>
<para>Refers to a method where a tree structure (for example, a
set of PCI buses connected by PCI to PCI bridges) is traversed
from the top to the bottom before all the siblings at any
particular level are acted upon.</para>
</entry>
</row>
<row>
<entry>
<para>DR Connector (DRC)</para>
</entry>
<entry>
<para>The term &#8220;DR connector&#8221; will be used here to
define the plug-in point for the entity that is participating in
DR. For example, a &#8216;slot&#8217; into which a PCI IOA is
inserted is a DRC.</para>
</entry>
</row>
<row>
<entry>
<para>DR Entity</para>
</entry>
<entry>
<para>An entity that can participate in DR operations. That is,
an entity that can be added or removed from the platform while
the platform power is on and the system remains operational. See
also the definitions of logical and physical DR entities.</para>
</entry>
</row>
<row>
<entry>
<para>DR Operation</para>
</entry>
<entry>
<para>The act of removing, adding or replacing a DR
Entity.</para>
</entry>
</row>
<row>
<entry>
<para>Entity</para>
</entry>
<entry>
<para>One or more I/O devices, IOAs, Processor cards, etc., that
are treated as one unit.</para>
</entry>
</row>
<row>
<entry>
<para>High Availability (HA) System</para>
</entry>
<entry>
<para>A system that gives the customer &#8220;close&#8221; to
continuous availability, but allows for some system down-time.
Besides DR, other factors that need to be considered in the
design of an HA system include system partitioning, clustering,
redundancy, error recovery, failure prediction, Error Detection
and Fault Isolation (EDFI), software failure detection/recovery,
etc.</para>
</entry>
</row>
<row>
<entry>
<para>I/O Adapter (IOA)</para>
</entry>
<entry>
<para>A device which attaches to a physical bus which is capable
of supporting I/O (a physical IOA) or logical bus (a virtual IOA)
and which has its own separate set of resources is referred to as
an IOA. The term &#8220;IOA&#8221; without the usage of the
qualifier &#8220;physical&#8221; or &#8220;virtual&#8221; will be
used to designate a physical IOA. Virtual IOAs are defined
further in
<xref linkend="dbdoclet.50569348_71217" />. Resources which must
have the capability of being separate (from other devices)
include: MMIO Load/Store address spaces, configuration address
spaces, DMA address spaces, power domains, error domains,
interrupt domains, and reset domains. Note that the hardware of
an IOA may allow for separation of these resources but the
platform or system implementation may limit the separation (for
example, shared error domains). In PCI terms, an IOA may be
defined by a unique combination of its assigned bus number and
device number, but not including its function number; an IOA may
be a single or multi-function device, unless otherwise specified
by the context of the text. Examples include LAN and SCSI IOAs. A
PCI IOA may exist as multiple device nodes in the OF device tree;
that is, the OF may treat separate &#8220;functions&#8221; in an
IOA as separate OF device tree nodes.</para>
</entry>
</row>
<row>
<entry>
<para>IOA: built-in</para>
</entry>
<entry>
<para>An IOA that is not pluggable by the user. Sometimes called
integrated I/O. As opposed to an IOA that may be removed as part
of a plug-in card removal (see definition for a plug-in card,
below).</para>
</entry>
</row>
<row>
<entry>
<para>I/O Bus</para>
</entry>
<entry>
<para>A hardware interface onto which an IOA can be plugged on a
platform. I/O buses discussed here include:</para>
</entry>
</row>
<row>
<entry>
<para>I/O Bus: PCI</para>
</entry>
<entry>
<para>The term &#8220;PCI&#8221; refers to one of: conventional
PCI, PCI-X, or PCI Express. The term &#8220;bus&#8221; in the
case of PCI Express refers to a PCI Express link.</para>
</entry>
</row>
<row>
<entry>
<para>I/O Bus: System Bus</para>
</entry>
<entry>
<para>The system bus in a platform is normally used only to
attach CPUs, memory controllers, and Host Bridges to bridge to
I/O buses. A platform&#8217;s system bus may, in certain
circumstances, be used to attach very high speed IOAs. DR of
system bus-attached entities is not considered here.</para>
</entry>
</row>
<row>
<entry>
<para>I/O Device</para>
</entry>
<entry>
<para>An entity that is connected to an IOA (usually through a
cable). A SCSI-attached DASD device is an example. Some I/O
devices and their connection points to the IOAs are designed to
be plugged while the connection point is operational to the other
I/O devices connected to the same IOA, and some are not. For
example, while the SCSI bus was not initially designed to have
devices added and removed while the SCSI bus was operational,
different vendors have found ways to do so. For example,
SCSI-attached DASD is pluggable and unpluggable from the SCSI bus
in some platforms.</para>
</entry>
</row>
<row>
<entry>
<para>Live Insertion</para>
</entry>
<entry>
<para>A DR operation where the power remains on at the DR
connector. Live insertion entities are always powered unless the
machine power is shut off or unless a subsystem containing those
entities is shut off.</para>
</entry>
</row>
<row>
<entry>
<para>Logical DR entity</para>
</entry>
<entry>
<para>A DR entity which does not have to be physically plugged or
unplugged during a DR operation on that entity. See
<xref linkend="dbdoclet.50569368_97022" /> for a list of the supported
Logical DR types.</para>
</entry>
</row>
<row>
<entry>
<para>Logical Resource DR</para>
</entry>
<entry>
<para>The name of the option for support of DR of logical
entities. See
<xref linkend="dbdoclet.50569342_75053" />.</para>
</entry>
</row>
<row>
<entry>
<para>PCI Hot Plug</para>
</entry>
<entry>
<para>DR for PCI plug-in cards where there is a separate power
domain for each PCI Hot Plug slot. Platforms which do not provide
individual control of power and isolation for each PCI slot but
which do provide power and isolation control for groups of PCI
slots (that is, multiple slots per power domain), do not provide
&#8220;PCI Hot Plug,&#8221; but can support PCI DR.</para>
</entry>
</row>
<row>
<entry>
<para>Physical DR entity</para>
</entry>
<entry>
<para>A DR entity which may need to be physically plugged or
unplugged during a DR operation on that entity. See
<xref linkend="dbdoclet.50569368_97022" /> for a list of the supported
physical DR types.</para>
</entry>
</row>
<row>
<entry>
<para>Plug-in card</para>
</entry>
<entry>
<para>A card which can be plugged into an I/O connector in a
platform and which contains one or more IOAs and potentially one
or more I/O bridges or switches.</para>
</entry>
</row>
<row>
<entry>
<para>Subsystem</para>
</entry>
<entry>
<para>One or more I/O devices, IOAs, Processor cards, etc., that
are treated as one unit, for purposes of
removal/insertion.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="dbdoclet.50569342_67883">
<title>Architectural Limitations</title>
<para>The DR architecture places a few limitations on the implementations.
Current architectural limitations include:</para>
<itemizedlist>
<listitem>
<para>DR operations will be user initiated at the software level before
any physical plugging or unplugging of hardware is performed. This
architecture will be flexible enough to add additional methods for invoking
the process in the future, but for the initial architecture it will be
assumed that the operation is invoked by the user via a software method
(for example, invoking an OS DR services program). It is expected that some
technologies which will be added in the future will allow
plugging/unplugging without the user first informing the software (for
example, P1394 and USB).</para>
</listitem>
<listitem>
<para>Critical system resources cannot be removed via a DR operation.
Which system resources are critical will not be defined by this
architecture; it is expected that this determination will be made by the OS
implementation and/or architecture. Loss of a critical resource would stop
the system from operating.</para>
</listitem>
<listitem>
<para>Many of the RTAS calls will need to work properly, independent of
what is powered-off (for example, NVRAM access must work during DR
operations). This is partially encompassed by the last bullet. For more
information, see
<xref linkend="dbdoclet.50569342_98936" />.</para>
</listitem>
<listitem>
<para>Any special requirements relative to redundant power supplies or
cooling are not addressed here.</para>
</listitem>
<listitem>
<para>Moving of a DR entity from one location to another in a platform is
supported through a &#8220;remove and add&#8221; methodology rather than a
specific architecture which defines the constructs necessary to allow
moving of pieces of the platform around.</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Note:</emphasis> The current AIX implementation does a &#8220;remove and
add&#8221; sequence even when the overall DR operation is a replacement.
That is, first the old entity is removed, and then the new entity is
added.</para>
</section>
<section xml:id="dbdoclet.50569342_69828">
<title>Dynamic Reconfiguration State Transitions</title>
<para>
<xref linkend="dbdoclet.50569342_17600" /> shows the states and transitions
for the dynamic reconfiguration entities (DR Entities). The transition
between states is initiated by a program action (RTAS functions) provided
the conditions for the transition are met.</para>
<para>
<emphasis role="bold">Note:</emphasis> Relative to
<xref linkend="dbdoclet.50569342_17600" />, physical DRC types are brought
in to the &#8220;owned by the OS&#8221; states either: (1) by the Device
Tree at boot time, or (2) by a DLPAR operation, which brings in the logical
DRC &#8220;above&#8221; the physical DRC first, and drags the physical in
as part of transferring from state 3 to state 4. Therefore no states appear
in the &#8220;owned by platform&#8221; section under Hot Plug DR in the
figure. So, for example, the DLPAR assignment of a PCI physical slot to an
OS is done by assigning the logical SLOT DRC above the physical PCI slot,
thus giving the following state transitions: state 1, to state 2, to state
3, to state 4, at which time the OS sees the physical slot, sees an IOA in
the physical slot (via
<emphasis>get-sensor-state</emphasis> (dr-entity-sense) of the physical DRC
returning &#8220;present&#8221;), and then proceeds with the state
transitions of: state 5, to state 6, to state 7, to state 8. The reverse of
this (DLPAR removal of the PCI slot) is: state 8, to state 6, to state 5,
to state 4, to state 2, to state 1.</para>
<para />
<figure xml:id="dbdoclet.50569342_17600">
<title>Dynamic Reconfiguration State Transition Diagrams</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-19.gif" format="GIF" scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-19.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para><emphasis role="bold">Notes:</emphasis>
<orderedlist>
<listitem>
<para>In State 5, if empty status is returned from the
get-sensor-state dr-entity-sense call, then do not attempt to power-on</para>
</listitem>
<listitem>
<para>Transitions from State 8 to 6 or from State 6 to 5 may fail
(<emphasis>set-indicator isolation-state</emphasis> isolate, and <emphasis>get-sensor-state</emphasis>
dr-entity-sense) if the hardware cannot be accessed to control
these operations. In this case, the OS may ignore
those errors if the operation is a DLPAR to remove the
hardware. See also the <emphasis role="bold"><literal>&#8220;ibm,ignore-hp-po-fails-for-dlpar&#8221;</literal></emphasis>
property in <xref linkend="dbdoclet.50569368_54493" />.</para>
</listitem>
</orderedlist>
</para>
</section>
<section>
<title>Base DR Option</title>
<section xml:id="dbdoclet.50569342_98936">
<title>For All DR Options - Platform Requirements</title>
<para>This section contains the extra requirements placed on
the platform for all of the various DR configurations.</para>
<para>At this time, there are no provisions made in the DR architecture
for unexpected removal of hardware or insertion of hardware into a DR
connector. Therefore the user is expected to interact with the DR
software prior to changing the hardware configuration. For example, it is
expected that most systems will require a keyboard action prior to the
hardware configuration change. Future architecture might allow for other
possibilities. For example, a push-button switch at the DR connector may
be provided which causes an interrupt to the OS to signal that an
operation is about to take place on the connector<footnote xml:id="pgfId-546764">
<para>The push-button method is one that has been mentioned as a
possible enhancement for systems that are produced for telephone
company applications.</para>
</footnote>.</para>
<para>As mentioned in
<xref linkend="dbdoclet.50569342_51213" />, the requirements in this
section are not stand-alone requirements; the platform will also need to
implement one or more of the specific DR options.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If the
<emphasis role="bold"><literal>&#8220;ibm,configure-connector&#8221;</literal></emphasis>
property exists in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node of the OF device tree, then the platform
must meet all of the requirements for the Base DR option (that is, all of
the requirements labeled &#8220;For all DR options&#8221;), and must also
meet all the requirements for at least one of the specific DR
options.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_22348">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The platform and
OS must adhere to the design and usage restrictions on RTAS routines
defined in
<xref linkend="dbdoclet.50569342_25194" />, and any RTAS calls not
specified in
<xref linkend="dbdoclet.50569342_25194" /> must comply with
<xref linkend="dbdoclet.50569342_25194" /> Note
<xref linkend="dbdoclet.50569342_82266" /> and
<xref linkend="dbdoclet.50569342_52602" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_25194">
<title>RTAS Call Operation During DR Operations</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" align="center" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">
<emphasis>RTAS Call Name</emphasis>
</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Reference to
<xref linkend="dbdoclet.50569342_25194" xrefstyle="select: labelnumber" /> Note
Numbers</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">&#160;</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">
<emphasis>RTAS Call Name</emphasis>
</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Reference to
<xref linkend="dbdoclet.50569342_25194" xrefstyle="select: labelnumber" /> Note
Numbers</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis>rtas-last-error</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry morerows='12'>
<para>&#160;</para>
</entry>
<entry>
<para>
<emphasis>ibm,read-pci-config</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>check-exception</emphasis>
</para>
</entry>
<entry>
<para>1, 2</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>ibm,write-pci-config</emphasis>
</para>
</entry>
<entry>
<para>4,7</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>display-character</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>restart-rtas</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>event-scan</emphasis>
</para>
</entry>
<entry>
<para>1, 2</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>set-indicator</emphasis>
</para>
</entry>
<entry>
<para>3, 4, 5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>query-cpu-stopped-state</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>set-power-level</emphasis>
</para>
</entry>
<entry>
<para>3, 4, 5</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>get-power-level</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>set-time-for-power-on</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>get-sensor-state</emphasis>
</para>
</entry>
<entry>
<para>3, 4</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>set-time-of-day</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>get-time-of-day</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>start-cpu</emphasis>
</para>
</entry>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,configure-connector</emphasis>
</para>
</entry>
<entry>
<para>7</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>stop-self</emphasis>
</para>
</entry>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,exti2c</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>system-reboot</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,os-term</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>nvram-store</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>nvram-fetch</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>
<emphasis>power-off</emphasis>
</para>
</entry>
<entry>
<para>1, 6</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>ibm,power-off-ups</emphasis>
</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<!--entry>
<para>&#160;</para>
</entry-->
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold"><xref linkend="dbdoclet.50569342_25194" xrefstyle="select: labelnumber" /> Notes:</emphasis>
<!--anchor xml:id="dbdoclet.50569342_35380" /-->
<orderedlist>
<listitem xml:id="dbdoclet.50569342_82266">
<para>These RTAS calls
function as specified in this architecture, regardless of the power state
of any DR entity in the platform (providing the call is
implemented).</para>
</listitem>
<listitem xml:id="dbdoclet.50569342_52602">
<para>These RTAS calls
do not cause errors nor return an error status by accessing hardware
which is isolated, unusable and/or powered down.</para>
</listitem>
<listitem>
<para>These RTAS calls function properly when dealing with a DR
connector, when the parent of that DR connector is powered and
configured, regardless of the state of the child of the parent (for
set-indicator, the isolation-state and dr-indicator names, and for
get-sensor-state, the dr-entity-sense sensor name).</para>
</listitem>
<listitem>
<para>The results of the OS issuing these RTAS calls to hardware when
the access to that hardware is through hardware which is isolated,
unusable, powered off, or incompletely configured, are
indeterminate.</para>
</listitem>
<listitem>
<para>The results of the OS changing the power or isolation state of a
Dynamic Reconfigure connector while there is an uncompleted
<emphasis>ibm,configure-connector</emphasis> operation in progress against
that connector are indeterminate.</para>
</listitem>
<listitem>
<para>Power domains which were defined within sub-trees which have
been subsequently isolated may remain un-modified by this call; their
state will be platform dependent.</para>
</listitem>
<listitem>
<para>The results of the OS issuing these RTAS calls to hardware which
is isolated and/or powered off are indeterminate.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If there is Forth code associated
with a DR entity, it must not modify the OF device tree properties or
methods unless modifications can be hidden by the
<emphasis>ibm,configure-connector</emphasis> RTAS call (that is, where
this RTAS routine recognizes the entity and creates the appropriate OF
device tree characteristics that would have been created by the Forth
code).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The hardware must protect against
any physical damage to components if the DR entity is removed or inserted
while power is on at the DR connector.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> During a DR operation (including
resetting and removing the reset from the entity, powering up and
powering down the entity, unisolating and isolating the entity, and
physically inserting and removing the entity), the platform must prevent
the introduction of unrecoverable errors on the bus or interconnect into
which the DR entity is being inserted or removed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> During a DR operation (including
resetting and removing the reset from the entity, powering up and
powering down the entity, unisolating and isolating the entity, and
physically inserting and removing the entity), the platform must prevent
damage to the DR entity and the planar due to any electrical
transitions.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_48304">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If there are any
live insertion DR entities in a platform and if those entities or the
rest of the platform cannot tolerate the power being turned off to those
entities during DR operations on other DR entities, then they must not be
placed in the same power domain as the DR entities that will be powered
off.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_36468">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> A separate visual
indicator must be provided for each physical DR connector which can be
used for insertion of a DR Entity or which contains a DR entity that can
be removed, and the indicator must be individually controllable via the
<emphasis>set-indicator</emphasis> RTAS call, and must have the capability
to be set to the states as indicated in
<xref linkend="dbdoclet.50569342_34333" /> and
<xref linkend="dbdoclet.50569342_42695" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_50603">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
If a platform provides a separate indicator to indicate the state of the power for the
DR connector, then that LED must be turned on by the platform when the
platform turns the power on to the DR connector and must be turned off by
the platform when the platform turns the power off to the DR
connector.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If a DR entity requires power to
be turned off prior to the physical removal of the DR entity from the
platform, then the hardware must provide a green power indicator to
indicate the power state of the DR entity</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The platform must provide any
necessary power sequencing between voltages within a power domain during
DR operations (for example, during the
<emphasis>set-power-level</emphasis> RTAS call).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_98936"
xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If a platform supports DR, then
all DR entities must support the full on to off and the off to full on
power transitions.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> Requirement
<xref linkend="dbdoclet.50569342_22348" /> is necessary so that the OS can
count on the availability of certain RTAS facilities and so that the OS
does not use other RTAS facilities when they are not available. This may
put certain hardware restrictions on what can and cannot be shut
down.</para>
<para>
<emphasis role="bold">Hardware Implementation Notes:</emphasis>
</para>
<itemizedlist>
<listitem>
<para>Requirement
<xref linkend="dbdoclet.50569342_22348" /> requires careful planning of
hardware design and platform structure to assure that no resources
critical to RTAS are put into power domains that are powered down as part
of a DR operation. In addition, the platform is required to provide the
facilities (registers and bits in registers readable by firmware, etc.)
so that RTAS can query the state of the hardware and determine if
something is powered off before actually accessing the powered-off
hardware.</para>
</listitem>
<listitem>
<para>Requirement
<xref linkend="dbdoclet.50569342_36468" /> indicates that there cannot be
any sharing of indicators between DR connectors.</para>
</listitem>
<listitem>
<para>In some large systems (for example, systems with many racks of
equipment) it may not be possible or convenient to view the individual DR
visual indicators without opening cabinet doors, etc. In such cases, the
designers of such systems could consider putting a &#8220;summary&#8221;
visual indicator where the user could readily see it, which is basically
a logical &#8220;or&#8221; of the visual indicators which are out of
sight. For example, in a rack-based system, the drawers might have an
indicator on the front of the drawer that indicates if any indicators on
the back of the drawer are flashing. This summary indicator will not be
accessed by the software (that is, will be transparent to the software)
but it is permissible for the indicator to have firmware
dependencies.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_82208">
<title>For All DR Options - OF Requirements</title>
<para>This section describes the OF properties added for DR and any
additional requirements placed on OF due to DR.</para>
<para>This section defines a number of new DR properties which are
arrays. All properties for a specific DR connector under a node are at
the same offset into each array. Also, when the descriptive text states
&#8220;the first connector&#8221; this does not imply any physical
position or numbering, but rather a logical &#8220;first&#8221; connector
beneath a particular node in the OF device tree.</para>
<section>
<title>General Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_82208"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> When the firmware passes control
to the OS, the DR hardware must be initialized such that all of the DR
connectors which would return &#8220;DR entity present&#8221; to a
<emphasis>get-sensor-state</emphasis> dr-entity-sense) are fully powered
and operational and any DR visual indicators are set to the appropriate
state (on or off) as indicated by
<xref linkend="dbdoclet.50569342_42695" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_82208"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> After the firmware has passed
control to the OS, the state of the DR visual indicators must not change
except under the following conditions:</para>
<itemizedlist>
<listitem>
<para>As directed to do so by the
<emphasis>set-indicator</emphasis> RTAS call.</para>
</listitem>
<listitem>
<para>Under the condition of a power-fault, in which case the hardware
may change the state of the visual indicator to the &#8220;off&#8221;
state if it turns the power off to the slot.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_82208"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The platforms which have
hierarchical power domains must provide the
<emphasis role="bold"><literal>&#8220;power-domains-tree&#8221;</literal></emphasis> property in the OF
device tree.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_17435">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify for each DR
connector an index to be passed between the OS and RTAS to identify the
DR connector to be operated upon. This property is in the parent node of
the DR connector to which the property applies. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property. See <xref linkend="sec_ibmdrcinfo_property" /> for additional information.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_17435"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> For each OF device tree node
which supports DR operations on its children, the OF must provide an
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property for that
node.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_31379">
<title><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify for each node
which has a DR connector between it and its parent, the value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property for that
connector. This property is used for correlation purposes. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_31379"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> For each OF device tree node
which has a DR connector between it and its parent, the OF must provide an
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> property for that
node.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_22748">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify for each DR
connector a user-readable location code for the connector. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property. See <xref linkend="sec_ibmdrcinfo_property" /> for additional information.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_22748"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> For each OF device tree node
which supports DR operations on its children, the OF must provide an
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> property for that
node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_22748"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The content of the
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> property must be of the
format defined in
<xref linkend="dbdoclet.50569342_62318" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_62318">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> Property Format</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">DRC Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">DRC Name</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1-8, 11-30 (PCI Hot Plug)</para>
</entry>
<entry>
<para>Location code</para>
</entry>
</row>
<row>
<entry>
<para>SLOT</para>
</entry>
<entry>
<para>Location code (built-in has port suffix)</para>
</entry>
</row>
<row>
<entry>
<para>PORT</para>
</entry>
<entry>
<para>Port x</para>
</entry>
</row>
<row>
<entry>
<para>CPU</para>
</entry>
<entry>
<para>CPU x</para>
<para>where &#8220;x&#8221; is a decimal number with one or
more digits and no leading zeroes</para>
</entry>
</row>
<row>
<entry>
<para>MEM or MEM-n</para>
</entry>
<entry>
<para>LMB x</para>
<para>where &#8220;x&#8221; is a decimal number with one or
more digits and no leading zeroes</para>
</entry>
</row>
<row>
<entry>
<para>PHB</para>
</entry>
<entry>
<para>PHB x</para>
<para>where &#8220;x&#8221; is a decimal number with one or
more digits and no leading zeroes</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFAC</para>
</entry>
<entry>
<para>location code</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFUN</para>
</entry>
<entry>
<para>location code</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="dbdoclet.50569342_86369">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify for each DR
connector the power domain in which the connector resides. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property. See <xref linkend="sec_ibmdrcinfo_property" /> for additional information.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569342_45966">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_86369"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
For each OF device tree node which supports DR operations on its children, the OF
must provide an
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis> property for that
node.</para>
<para><emphasis role="bold">Software Implementation Notes:</emphasis>
<itemizedlist>
<listitem>
<para>Software will not call the
<emphasis>set-power-level</emphasis> RTAS call with an invalid power
domain number, and for purposes of this call, a power domain number of -1
(a live insert connector) is considered invalid.</para>
</listitem>
<listitem>
<para>For the case where the power domain is -1 (the live insert case),
this does not imply that the connector does not need isolating before the
DR operation, only that it does not need to be powered off.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_27002">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify for each DR
connector a user-readable connector type for the connector. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property. See <xref linkend="sec_ibmdrcinfo_property" /> for additional information.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The logical connectors (CPU, MEM
etc.) represent DR boundaries that may not have physical DR connectors
associated with them. If a physical DR boundaries were present they would
be represented by a different DR connector type. It is possible that a
given boundary may be represented by both a physical and a logical
connector. In that case, logical assignment would be managed with the
logical connector and physical add/remove would be managed by specifying
the physical DR connector.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_27002"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> For each OF device tree node
which supports DR operations on its children, the OF must provide an
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> property for that
node.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_79298">
<title><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> Property</title>
<para>This property is added for the DR option to specify the phandle for
each OF device tree node returned by ibm,configure-connector. See
<xref linkend="dbdoclet.50569368_13582" /> for the definition of this
property.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_79298"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The
<emphasis>ibm,configure-connector</emphasis> RTAS call will include the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property in each OF device
tree node that it returns. This phandle must be unique and consistent
with any phandle visible to an OF client program or any other information
returned by
<emphasis>ibm,configure-connector</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_ibmdrcinfo_property">
<title><emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> Property</title>
<para>This property is added to consolidate the information provided by the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis> properties.
When present, it replaces those properties.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibmdrcinfo_property"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para>For each OF device tree node which supports DR operations on its children, OF must
provide an <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property for that node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibmdrcinfo_property"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para>The <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property shall only
be present if the Operating System indicates support for this new property definition,
otherwise, the <emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis> will be present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibmdrcinfo_property"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para>Following live partition migration the Operating System must be prepared to support
either the <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property or the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>
set of properties. The property or properties presented will based on the capability of the target partition.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569342_40601">
<title>For All DR Options - RTAS Requirements</title>
<para>For platforms that implement DR, there is one new RTAS call and
some changes (new requirements) placed on existing ones.</para>
<section>
<title>General Requirements</title>
<para>The following are the general requirements for RTAS for all DR
options.</para>
<variablelist>
<varlistentry xml:id="dbdoclet.50569342_40266">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_40601"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
If there is Forth
code associated with a DR entity and that Forth code would normally
modify the OF device tree properties or methods, then if that entity is
to be supported as a DR entity on a particular platform, the
<emphasis>ibm,configure-connector</emphasis> RTAS call on that platform
must recognize that entity and create the appropriate OF device tree
characteristics that would have been created by the Forth code.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_set_power_level">
<title><emphasis>set-power-level</emphasis></title>
<para>This RTAS call is defined in
<xref linkend="dbdoclet.50569332_45884" />. Several additional requirements are placed
on this call when the platform implements DR along with PM.</para>
<para>This RTAS call is used in DR to power up or power down a DR
connector, if necessary (that is, if there is a non-zero power domain
listed for the DR connector in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property). The
input is the power domain and the output is the power level that is
actually to be set for that domain; for purposes of DR, only two of the
current power levels are of interest: &#8220;full on&#8221; and
&#8220;off.&#8221;</para>
<para>For sequencing requirements between this RTAS routine and others,
see Requirements
<xref linkend="dbdoclet.50569342_25655" /> and
<xref linkend="dbdoclet.50569342_75542" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_set_power_level"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> the
<emphasis>set-power-level</emphasis> RTAS call must be implemented as
specified in
<xref linkend="dbdoclet.50569332_45884" /> and the further requirements of this DR
option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_set_power_level"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The
<emphasis>set-power-level</emphasis> RTAS call must initiate the operation
and return &#8220;busy&#8221; status for each call until the operation is
actually complete.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_35664">
<term><emphasis role="bold">R1-<xref linkend="sec_set_power_level"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
If a DR operation
involves the user inserting a DR entity, then if the firmware can
determine that the inserted entity would cause a system disturbance, then
the
<emphasis>set-power-level</emphasis> RTAS call must not power up the
entity and must return an error status which is unique to that particular
type of error, as indicated in
<xref linkend="dbdoclet.50569342_91238" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_91238">
<title><emphasis>set-power-level</emphasis> Error Status for specific DR
options</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="25*" align="center" />
<colspec colname="c4" colwidth="45*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Option Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>PCI Hot Plug DR option</para>
</entry>
<entry>
<para>-9000: Powering entity would create change of frequency
on the bus and would disturb the operation of other PCI IOAs on
the bus, therefore entity not powered up.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para><emphasis role="bold">Hardware Implementation Notes:</emphasis>
<itemizedlist>
<listitem>
<para>For any DR operation, the firmware could optionally not allow
powering up of a DR entity, if the powering up would cause a platform
over-power condition (the firmware would have to be provided with the DR
Entities&#8217; power requirements and the platform&#8217;s power
capability by a method which is not architected by the DR
architecture).</para>
</listitem>
<listitem>
<para>If PM is not implemented in the platform, then only the
&#8220;full on&#8221; and &#8220;off&#8221; states need to be implemented
for DR and only those two states will be used.</para>
</listitem>
</itemizedlist>
</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> The operation of the
<emphasis>set-power-level</emphasis> call is not complete at the time of
the return from the call if the &#8220;busy&#8221; status is returned. If
it is necessary to know when the operation is complete, the routine
should be called with the same parameters until a non-busy status is
returned.</para>
</section>
<section xml:id="dbdoclet.50569342_85040">
<title><emphasis>get-sensor-state</emphasis></title>
<para>This RTAS call is defined in
<xref linkend="dbdoclet.50569342_85040" />. This RTAS call will be used
in DR to determine if there is something connected to the DR
connector.</para>
<para>The
<emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,sensor-&lt;token&gt;&#8221;</literal></emphasis>
OF properties are not applicable to DR
sensors defined in
<xref linkend="dbdoclet.50569342_92542" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_85040"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> RTAS must implement the
<emphasis>get-sensor-state</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_85040"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The sensor values specified in
<xref linkend="dbdoclet.50569342_92542" /> must be implemented as
specified in that table.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_92542">
<title><emphasis>get-sensor-state</emphasis> Defined Sensors for All DR
Options</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="35*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Sensor Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Token Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Defined Sensor Values</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry morerows="4">
<para>dr-entity-sense</para>
</entry>
<entry morerows="4">
<para>9003</para>
</entry>
<entry>
<para>DR connector empty (0)</para>
</entry>
<entry>
<para>Returned for physical DR entities if the connector is
available (empty) for an add operation. The DR connector must
be allocated to the OS to return this value, otherwise a status
of -3, no such sensor implemented, will be returned from the
<emphasis>get-sensor-state</emphasis> RTAS call.</para>
</entry>
</row>
<row>
<entry>
<para>DR entity present (1)</para>
</entry>
<entry>
<para>Returned for logical and physical DR entities when the DR
connector is allocated to the OS and the DR entity is present.
For physical DR entities, this indicates that the DR connector
actually has a DR entity plugged into it. For DR connectors of
physical DR entities, the DR connector must be allocated to the
OS to return this value, otherwise a status of -3, no such
sensor implemented, will be returned from the
<emphasis>get-sensor-state</emphasis> RTAS call. For DR
connectors of logical DR entities, the DR connector must be
allocated to the OS to return this value, otherwise a sensor
value of 2 or 3 will be returned.</para>
</entry>
</row>
<row>
<entry>
<para>DR entity unusable (2)</para>
</entry>
<entry>
<para>Returned for logical DR entities when the DR entity is
not currently available to the OS, but may possibly be made
available to the OS by calling
<emphasis>set-indicator</emphasis> with the allocation-state
indicator, setting that indicator to usable.</para>
</entry>
</row>
<row>
<entry>
<para>DR entity available for exchange (3)</para>
</entry>
<entry>
<para>Returned for logical DR entities when the DR entity is
available for exchange in a sparing type operation, in which
case the OS can claim that resource by doing a
<emphasis>set-indicator</emphasis> RTAS call with
allocation-state set to exchange.</para>
</entry>
</row>
<row>
<entry>
<para>DR entity available for recovery (4)</para>
</entry>
<entry>
<para>Returned for logical DR entities when the DR entity can
be recovered by the platform and used by the partition
performing a
<emphasis>set-indicator</emphasis> RTAS call with
allocation-state set to recover.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_64410" >
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_85040"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options except the PCI Hot Plug and LRDR
options:</emphasis>
If the
<emphasis>get-sensor-state</emphasis> call with the dr-entity-sense sensor
requires the DR entity to be powered up and/or unisolated to sense the
presence of the DR entity, then the
<emphasis>get-sensor-state</emphasis> call must return the error code of
-9000 or -9001, as defined in
<xref linkend="dbdoclet.50569342_44990" />, if the DR entity is powered
down or is isolated when the call is made.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_44990">
<title><emphasis>get-sensor-state</emphasis> Error Status for All DR
Options</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>Status</para>
</entry>
<entry>
<para>-9000: Need DR entity to be powered up and unisolated
before RTAS call</para>
<para>-9001: Need DR entity to be powered up, but not
unisolated, before RTAS call</para>
<para>-9002: (see architecture note, directly below)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The -9002 return code should not
be implemented. For legacy implementations if it is returned, then it
should be treated by the caller the same as a return value of 2 (DR
entity unusable).</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_43470">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_85040"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
The value used
for the sensor-index input to the
<emphasis>get-sensor-state</emphasis> RTAS call for the sensors in
<xref linkend="dbdoclet.50569342_92542" /> must be the index for the
connector, as passed in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property.</para>
<para>
<emphasis role="bold">Hardware and Software Implementation Note:</emphasis> The status
introduced in Requirement
<xref linkend="dbdoclet.50569342_64410" /> is not valid for
<emphasis>get-sensor-state</emphasis> calls when trying to sense insertion
status for PCI slots (see Requirement
<xref linkend="dbdoclet.50569342_94933" />).</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> DR entity available for recovery
state is intended to allow a platform to temporary allocate to itself
resources on a reboot and then allow the OS to subsequently recover those
resources when no longer needed by the platform. An example of use would
be the platform temporarily reserving some LMBs to itself during a reboot
to store dump data, and then making the LMBs available to a OS partition
by marking them with the state of &#8220;available for recovery&#8221;
after the dump data has been transferred to the OS.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_61130">
<title><emphasis>set-indicator</emphasis></title>
<para>This RTAS call is defined as shown in
<xref linkend="dbdoclet.50569332_27587" />. This RTAS call is used in DR to transition
between isolation states, allocation states, and control DR indicators.
In some cases, a state transition fails due to various conditions,
however, a null transition (commanding that the new state be what it
already is) always succeeds. As a consequence, this RTAS call is used in
all DR sequences to logically (and if necessary physically) isolate and
unisolate the connection between a DR entity and the platform. If
physical isolation is indeed required for the DR entity, this RTAS call
determines the necessity for isolation, not the calling program.</para>
<para>The
<emphasis>set-indicator</emphasis> allocation-state and
<emphasis>set-indicator</emphasis> isolation-state are linked. Before
calling
<emphasis>set-indicator</emphasis> with isolation-state set to unisolate,
the DR entity being unisolated will first need to be allocated to the OS.
If the
<emphasis>get-sensor-state</emphasis> call would return a value of DR
entity unusable or if it would return an error like -3 for the DR entity,
then the
<emphasis>set-indicator</emphasis> isolation-state to unisolate would fail
for that DR entity.</para>
<para>For sequencing requirements between this RTAS routine and others,
see Requirements
<xref linkend="dbdoclet.50569342_25655" /> and
<xref linkend="dbdoclet.50569342_75542" />.</para>
<para>A single
<emphasis>set-indicator</emphasis> operation for indicator type 9001 may
require an extended period of time for execution. Following the
initiation of the hardware operation, if the
<emphasis>set-indicator</emphasis> call returns prior to successful
completion of the operation, the call will return either a status code of
-2 or 990x. A status code of -2 indicates that RTAS may be capable of
doing useful processing immediately. A status code of 990x indicates that
the platform requires an extended period of time, and hints at how much
time will be required before completion status can be obtained. Neither
the 990x nor the -2 status codes imply that the platform has initiated
the operation, but it is expected that the 990x status would only be used
if the operation had been initiated.</para>
<para>The following are the requirements for the base DR option. Other DR
options may put additional requirements on this RTAS call.</para>
<para>
<xref linkend="dbdoclet.50569342_34333" /> indicates which DR indicators
are used with which DR connector types.</para>
<para>The
<emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,indicator-&lt;token&gt;&#8221;</literal></emphasis>
OF properties are not applicable to DR
indicators defined in
<xref linkend="dbdoclet.50569342_34333" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The indicator state values
specified in
<xref linkend="dbdoclet.50569342_34333" /> must be implemented as
specified in that table.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_34333">
<title><emphasis>set-indicator</emphasis> Defined Indicators for all DR
Options</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="15*" align="center" />
<colspec colname="c4" colwidth="10*" align="center" />
<colspec colname="c5" colwidth="50*" />
<thead valign="middle">
<row>
<entry>
<para>
<emphasis role="bold">Indicator Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Token Value</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Defined State Values</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Default Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Examples/Comments</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>isolation-state</para>
</entry>
<entry>
<para>9001</para>
</entry>
<entry>
<para>Isolate (0),<?linebreak?>
Unisolate (1)</para>
</entry>
<entry>
<para>Unisolated</para>
</entry>
<entry>
<para>This indicator must be implemented for DR connectors for
both physical and logical DR entities. Isolate refers to the DR
action to logically disconnect the DR entity from the platform.
An isolate operation makes the DR entity available to the
firmware, and in the case of a physical DR entity like a PCI
IOA, logically disconnects the DR entity from the platform (for
example, from the PCI bus). Unisolate refers to the DR action
to logically connect the entity. Before
<emphasis>set-indicator</emphasis> isolation-state to unisolate,
the DR entity being unisolated must first be allocated to the
OS. If the
<emphasis>get-sensor-state</emphasis> call with the
dr-entity-sense token would return a value of DR entity
unusable or if it would return an error like -3 for the DR
entity, then the
<emphasis>set-indicator</emphasis> isolation-state to unisolate
must fail for that DR entity.</para>
</entry>
</row>
<row>
<entry>
<para>dr-indicator</para>
</entry>
<entry>
<para>9002</para>
</entry>
<entry>
<para>Inactive (0),<?linebreak?>
Active (1),<?linebreak?>
Identify (2)<?linebreak?>
Action (3)</para>
</entry>
<entry>
<para>0 if Inactive<?linebreak?>
1 if Active</para>
</entry>
<entry>
<para>This indicator must be implemented for DR connectors for
physical DR entities. If the DR indicators exist for the DR
connector, then they are used to indicate the state of the DR
connector to the user. Usage of these states are as defined in
<xref linkend="dbdoclet.50569342_42695" /> and
<xref linkend="dbdoclet.50569347_31867" />.</para>
</entry>
</row>
<row>
<entry>
<para>allocation-state</para>
</entry>
<entry>
<para>9003</para>
</entry>
<entry>
<para>unusable (0)<?linebreak?>
usable (1)<?linebreak?>
exchange (2)<?linebreak?>
recover (3)</para>
</entry>
<entry>
<para>NA</para>
</entry>
<entry>
<para>This indicator must be implemented for DR connectors for
logical DR entities. Used to allocate and deallocate entities
to the OS. The initial allocation state of a connector is
established based upon the initial allocation of resources to
the OS image. Subsequently, an OS may request a change of
allocation state by use of the
<emphasis>set-indicator</emphasis> with allocation-state token.
If the transition to the usable state is not possible the -3
(no such indicator implemented) status is returned.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_16260">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
The value used for the indicator-index input to the
<emphasis>set-indicator</emphasis> RTAS call for the indicators in
<xref linkend="dbdoclet.50569342_34333" /> must be the index for the
connector, as passed in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The
<emphasis>set-indicator</emphasis> call must return a -2 status, or
optionally for indicator type 9001 the 990x status, for each call until
the operation is complete; where the 990x status is defined in
<xref linkend="dbdoclet.50569332_10584" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If this is a DR operation that
involves the user inserting a DR entity, then if the firmware can
determine that the inserted entity would cause a system disturbance, then
the
<emphasis>set-indicator</emphasis> RTAS call must not unisolate the entity
and must return an error status which is unique to the particular
error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> If the
<emphasis>set-indicator</emphasis> index refers to a connector that would
return a &#8220;DR entity unusable&#8221; status (2) to the
<emphasis>get-sensor</emphasis> dr-entity-sense token, the
<emphasis>set-indicator</emphasis> RTAS return code must be &#8220;No such
indicator implemented&#8221; (-3), except in response to a successful
<emphasis>set-indicator</emphasis> allocation state usable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options combined with the LPAR option:</emphasis> The
RTAS
<emphasis>set-indicator</emphasis> specifying unusable allocation-state of
a DR connector must unmap the resource from the partition&#8217;s Page
Frame Table(s) and, as appropriate, its Translation Control Entry
tables.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_61130"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options combined with the LPAR option:</emphasis> The
successful completion of the RTAS
<emphasis>set-indicator</emphasis> specifying usable allocation-state of a
DR connector must allow subsequent mapping of the resource as appropriate
within the partition&#8217;s Page Frame Table(s) and/or its Translation
Control Entry tables.</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> The operation of the
<emphasis>set-indicator</emphasis> call is not complete at the time of the
return from the call if the &#8220;busy&#8221; status is returned. If it
is necessary to know when the operation is complete, the routine should
be called with the same parameters until a non-busy status is
returned.</para>
<para>
<emphasis role="bold">Hardware and Software Implementation Note:</emphasis> The
<emphasis>set-indicator</emphasis> (isolation-state) call is used to clear
RTAS internal tables regarding this device. The
<emphasis>ibm,configure-connector</emphasis> RTAS routine will need to be
called before using the entities below this connector, even if power was
never removed from an entity while it was in the isolated state.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_39636">
<title><emphasis>ibm,configure-connector</emphasis> RTAS Call</title>
<para>The RTAS function
<emphasis>ibm,configure-connector</emphasis> is a new RTAS call introduced
by DR and is used to configure a DR entity after it has been added by
either an add or replace operation. It is expected that the
<emphasis>ibm,configure-connector</emphasis> RTAS routine will have to be
called several times to complete the configuration of a dynamic
reconfiguration connector, due to the time required to complete the
entire configuration process. The work area contains the intermediate
state that RTAS needs to retain between calls. The work area consists of
4096 byte pages of real storage on 4096 byte boundaries which can be
increased by one page on each call. The OS may interleave calls to
<emphasis>ibm,configure-connector</emphasis> for different dynamic
reconfiguration connectors, however, a separate work area will be
associated with each dynamic reconfiguration connector which is actively
being configured. Other standard RTAS locking rules apply.</para>
<para>The properties generated by the
<emphasis>ibm,configure-connector</emphasis> call are dependent on the
type of DR entities. For a list of properties generated, see the RTAS
Requirements section for each specific DR option. For example, for a list
of properties generated for PCI Hot Plug, see
<xref linkend="dbdoclet.50569342_67543" />.</para>
<para>For sequencing requirements between this RTAS routine and others,
see Requirement
<xref linkend="dbdoclet.50569342_25655" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_39636"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The RTAS function
<emphasis>ibm,configure-connector</emphasis> must be implemented and must
implement the argument call buffer defined by
<xref linkend="dbdoclet.50569342_50675" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_50675">
<title><emphasis>ibm,configure-connector</emphasis> Argument Call Buffer</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15*" align="center" />
<colspec colname="c2" colwidth="15*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Parameter Type</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry morerows="4">
<para>In</para>
</entry>
<entry>
<para>
<emphasis>Token</emphasis>
</para>
</entry>
<entry>
<para>Token for
<emphasis>ibm,configure-connector</emphasis></para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Inputs</emphasis>
</para>
</entry>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Number Outputs</emphasis>
</para>
</entry>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Work area</emphasis>
</para>
</entry>
<entry>
<para>Address of work area</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis>Memory extent</emphasis>
</para>
</entry>
<entry>
<para>0 or address of additional page</para>
</entry>
</row>
<row>
<entry>
<para>Out</para>
</entry>
<entry>
<para>
<emphasis>Status</emphasis>
</para>
</entry>
<entry>
<para>-9003: Cannot configure - Logical DR connector unusable,
available for exchange, or available for recovery.</para>
<para>-9002: Cannot configure - DR Entity cannot be supported
in this connector</para>
<para>-9001 Cannot configure - DR Entity cannot be supported in
this system</para>
<para>-2: Call again</para>
<para>-1: Hardware error</para>
<para>0: Configuration complete</para>
<para>1: Next sibling</para>
<para>2: Next child</para>
<para>3: Next property</para>
<para>4: Previous parent</para>
<para>5: Need more memory</para>
<para>990X: Extended Delay</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_39636"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> On the first call of a dynamic
reconfiguration sequence, the one page work area must be initialized by
the OS as in
<xref linkend="dbdoclet.50569342_44663" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_44663">
<title>Initial Work Area Initialization</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Entry Offset</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>entry from the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property for
the connector to configure</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The entry offset in
<xref linkend="dbdoclet.50569342_44663" /> is either four bytes or eight
bytes depending on whether RTAS was instantiated in 32-bit or 64-bit
mode, respectively.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_39636"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> On all subsequent calls of the
sequence, the work area must be returned unmodified from its state at the
last return from RTAS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_39636"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The
<emphasis>ibm,configure-connector</emphasis> RTAS call must update any
necessary RTAS configuration state based upon the configuration changes
effected through the specified DR connector.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The sequence ends when either RTAS returns a &#8220;hardware
error&#8221; or &#8220;configuration complete&#8221; status code, at
which time the contents of the work area are undefined. If the OS no
longer wishes to continue configuring the connector, the OS may recycle
the work area and never recall RTAS with that work area. Unless the
sequence ends with Configuration Complete, the OS will assume that any
reported devices remain unconfigured and unusable. RTAS internal data
structures (outside of the work area) are not updated until the call
which returns &#8220;configuration complete&#8221; status. A subsequent
sequence of calls to
<emphasis>ibm,configure-connector</emphasis> with the same entry from the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> property will restart
the configuration of devices which were not completely configured.</para>
<para>If the index from
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> refers to a connector
that would return an &#8220;DR entity unusable&#8221; status (2) to the
<emphasis>get-sensor</emphasis> RTAS call with dr-entity-sense token, the
<emphasis>ibm,configure-connector</emphasis> RTAS call for that index
immediately returns &#8220;-9003: Cannot configure - Logical DR connector
unusable&#8221; on the first call without any configuration action taken
on the DR connector.</para>
<para>A dynamic reconfiguration connector may attach several sibling OF
device tree architected devices. Each such device may be the parent of
one or more device sub-trees. The
<emphasis>ibm,configure-connector</emphasis> RTAS routine configures and
reports the entire sub-tree of devices rooted in previously unconfigured
architected devices found below the connector whose index is specified in
the first entry of the work area, except those that are associated with
an empty or unowned dynamic reconfiguration connector; where unowned
refers to a DR connector that would return a DR entity unusable, a DR
entity available for exchange, or a DR entity available for entity
available for recovery value, for a
<emphasis>get-sensor</emphasis> dr-entity-sense sensor. Configuration
proceeds in a depth first order.</para>
<para>If the
<emphasis>ibm,configure-connector</emphasis> RTAS routine returns with the
&#8220;call again&#8221; or 990x status, configuration is proceeding but
had to be suspended to maintain the short execution time requirement of
RTAS routines. No results are available. The OS should call the
<emphasis>ibm,configure-connector</emphasis> RTAS routine passing back the
work area unmodified at a later time to continue the configuration
process.</para>
<para>If the
<emphasis>ibm,configure-connector</emphasis> RTAS routine returns with a
&#8220;Cannot configure - DR Entity cannot be supported in this
connector&#8221;, then there is a lack of one or more resources at this
connector for this DR Entity and there is at least one DR connector in
the system into which this DR Entity can be configured. In this case, the
DR program should indicate to the user that they need to consult the
appropriate system documentation relative to the DR Entity that they are
trying to insert into the system.</para>
<para>The &#8220;need more memory&#8221; status code, is similar in
semantics to the &#8220;call again&#8221; status. However, on the next
<emphasis>ibm,configure-connector</emphasis> call, the OS will supply, via
the
<emphasis>Memory extent</emphasis> parameter, the address of another page
of memory for RTAS to add to the work area in order for configuration to
continue. On all other calls to
<emphasis>ibm,configure-connector</emphasis> the contents of the
<emphasis>Memory extent</emphasis> parameter should be 0. It is the
responsibility of the OS to recover all work area memory after a sequence
of
<emphasis>ibm,configure-connector</emphasis> calls is completed.</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> The OS may allocate the
work area from contiguous virtual space and pass individual discontiguous
real pages to
<emphasis>ibm,configure-connector</emphasis> as needed.</para>
<para>If the
<emphasis>ibm,configure-connector</emphasis> RTAS routine returns either
the &#8220;next sibling&#8221; or &#8220;next child&#8221; status codes,
configuration has detected an architected OF device tree device, and is
returning its OF device tree node-name. Work Area offset 2 contains an
offset within the first page of the work area to a NULL terminated string
containing the node-name. Note, if the caller needs to preserve this or
any other returned parameters between the various calls of a
configuration sequence it will copy the value to its own area. Also, the
first call returning configuration data will have a &#8220;next
child&#8221; status code.</para>
<para>The &#8220;next property&#8221; status code indicates that a
subsequent property is being returned for the device. Work Area entry
offset 2 contains an offset within the first page of the work area to a
NULL terminated string containing the property name. Work Area entry
offset 3 contains the length of the property value in bytes. Work Area
entry offset 4 contains an offset within the first page of the work area
to the value of the property.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The
<emphasis>ibm,configure-connector</emphasis> RTAS routine returns those
applicable properties that can be determined without interpreting any
FCode ROM which is associated with the IOA. Additionally, it is
permissible for this RTAS call to be aware of various specific IOAs and
emulate the action of any FCode associated with the IOA.</para>
<para>If the
<emphasis>ibm,configure-connector</emphasis> RTAS routine returns the
&#8220;previous parent&#8221; status code, it has come to the end of the
string of siblings, and will back up the tree one level following its
depth first order algorithm. The 2nd through 4th work area entries are
undefined for this status code.</para>
<para>
<emphasis role="bold">Software Implementation Notes:</emphasis>
<orderedlist>
<listitem>
<para>Any attempts to configure an already configured connector or one
in progress of being configured will produce unpredictable
results.</para>
</listitem>
<listitem>
<para>The software will put the DR entity in the full on power state
before issuing the
<emphasis>ibm,configure-connector</emphasis> RTAS call to configure the DR
entity.</para>
</listitem>
</orderedlist>
</para>
</section>
</section>
<section xml:id="dbdoclet.50569342_16693">
<title>For All DR Options - OS Requirements</title>
<para />
<section xml:id="dbdoclet.50569342_83771">
<title>Visual Indicator States</title>
<para>DR Visual indicator usage will be as indicated in the following
requirement, in order to provide for a consistent user interface across
platforms. Information on implementation dependent aspects of the DR
indicators can be found in
<xref linkend="dbdoclet.50569347_31867" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_83771"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The visual indicators must be
used as defined in
<xref linkend="dbdoclet.50569342_42695" />.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_42695">
<title>Visual Indicator Usage</title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">State of indicator</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Usage</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>Inactive</para>
</entry>
<entry>
<para>The DR connector is inactive and entity may be removed or
added without system disruption. For DR entities that require
power off at the connector, then the caller of
<emphasis>set-indicator</emphasis> must turn power off prior to
setting the indicator to this state. See also
<xref linkend="dbdoclet.50569347_31867" />.</para>
</entry>
</row>
<row>
<entry>
<para>Identify (Locate)</para>
</entry>
<entry>
<para>This indicator state is used to allow the user to
identify the physical location of the DR connector. This state
may map to the same visual state (for example, blink rate) as
the Action state, or may map to a different state. See also
<xref linkend="dbdoclet.50569347_31867" />.</para>
</entry>
</row>
<row>
<entry>
<para>Action</para>
</entry>
<entry>
<para>Used to indicate to the user the DR connector on which
the user is to perform the current DR operation. This state may
map to the same visual state (for example, blink rate) as the
Identify state, or may map to a different state. See also
<xref linkend="dbdoclet.50569347_31867" />.</para>
</entry>
</row>
<row>
<entry>
<para>Active</para>
</entry>
<entry>
<para>The DR connector is active and entity removal may disrupt
system operation. See also
<xref linkend="dbdoclet.50569347_31867" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="sec_other_req">
<title>Other Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_other_req"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis> The OS must detect hierarchical
power domains (as specified in the
<emphasis role="bold"><literal>&#8220;power-domains-tree&#8221;</literal></emphasis> property) and must
handle those properly during a DR operation.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_25655">
<term><emphasis role="bold">R1-<xref linkend="sec_other_req"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
When bringing a
DR entity online, the OS must issue the following RTAS calls in the
following order:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>If the power domain is not 0, then call
<emphasis>set-power-level</emphasis></para>
</listitem>
<listitem>
<para><emphasis>set-indicator</emphasis> (with the isolation-state token and a
state value of unisolate)</para>
</listitem>
<listitem>
<para><emphasis>ibm,configure-connector</emphasis></para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_75542">
<term><emphasis role="bold">R1-<xref linkend="sec_other_req"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all DR options:</emphasis>
When taking a DR
entity offline, the OS must issue the following RTAS calls in the
following order:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para><emphasis>set-indicator</emphasis> with the isolation-state token and a
state value of isolate)</para>
</listitem>
<listitem>
<para>If the power domain is not 0, then call
<emphasis>set-power-level</emphasis></para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_other_req"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para>When bringing a DR entity online that
utilizes TCEs (see
<xref linkend="dbdoclet.50569328_76588" />), the OS must initialize the DR
entity's TCEs.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569342_47470">
<title>PCI Hot Plug DR Option</title>
<para>This section will develop the requirements over and beyond the base
DR option requirements, that are unique to being able to perform DR
operations on PCI plug-in cards that do not share power domains with other
PCI plug-in cards.</para>
<section xml:id="dbdoclet.50569342_71112">
<title>PCI Hot Plug DR - Platform Requirements</title>
<para>A method will be provided to isolate the plug-in card (power and
logic signals) and to physically remove the plug-in card from the
machine. The physical removal may pose an interesting mechanical
challenge, due to the position of the card edge connector relative to the
desired direction of insertion of the card from the outside of the
machine. In addition, PCI plug-in cards may have internal cables and may
span multiple slots. Such mechanical issues are not addressed by this
architecture.</para>
<para>This section describes the requirements for the platform when a
platform implements the PCI Hot Plug DR option.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> All platform
requirements of the base DR option architecture must be met (
<xref linkend="dbdoclet.50569342_98936" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> All PCI requirements
must be met (for example, timing rules, power slew rates, etc.) as
specified in the appropriate PCI specifications, and in the
<xref linkend="dbdoclet.50569387_87046" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_67003">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis>
The hardware must
provide two indicators per PCI Hot Plug slot, and all the following must
be true:
<orderedlist numeration="loweralpha">
<listitem>
<para>One indicator must be green and the platform must use the
indicator to indicate the power state of the PCI Hot Plug slot, turning
on the indicator when the slot power is turned on and turning off the
indicator when the slot power is turned off.</para>
</listitem>
<listitem>
<para>The other indicator must be amber and must be controllable by
RTAS, separately from all other indicators, and must be used as a slot
Identify indicator, as defined in
<xref linkend="dbdoclet.50569347_31867" />.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_31404">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis>
The hardware must
provide a separate power domain for each PCI Hot Plug slot, controllable
by RTAS, and that power domain must not be used by any other DR connector
in the platform.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_94933">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis>
The hardware must
provide the capability to RTAS to be able to read the insertion state of
each PCI Hot Plug slot individually and must provide the capability of
reading this information independent of the power and isolation status of
the plug-in card.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_17671">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis>
The hardware must
provide individually controllable electrical isolation (disconnect) from
the PCI bus for each PCI Hot Plug slot, controllable by RTAS and this
isolation when set to the isolation mode must protect against errors
being introduced on the bus, and damage to the plug-in cards or planars
during the plug-in card power up, power down, insertion, and
removal.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_33017">
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option:</emphasis>
A platform must
prevent the change in frequency of a bus segment (for example, on the
insertion or removal of an plug-in card) while that change of frequency
would result in improper operation of the system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option:</emphasis> For each PCI Hot Plug
slot which will accept only 32-bit (data width) plug-in cards, the
platform must:
<orderedlist numeration="loweralpha">
<listitem>
<para>Accommodate plug-in cards requiring up to 64 MB of PCI Memory
Space and 64 KB of PCI I/O space</para>
</listitem>
<listitem>
<para>For TCE-mapped DMA address space, must provide the capability to
map simultaneously and at all times at least 128 MB of PCI Memory space
for the slot.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option:</emphasis> Each PCI Hot Plug slot
which will accept 64-bit (data width) plug-in cards, the platform
must:
<orderedlist numeration="loweralpha">
<listitem>
<para>Accommodate plug-in cards requiring up to 128 MB of PCI Memory
Space and 64 KB of PCI I/O space</para>
</listitem>
<listitem>
<para>For TCE-mapped DMA address space, must provide the capability to
map simultaneously and at all times at least 256 MB of PCI Memory space
for the slot.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option with PCI Express:</emphasis> The
power and isolation controls must be implemented by use of the PCI
Standard Hot-Plug Controller (see
<emphasis> <xref linkend="dbdoclet.50569387_87046" /> </emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_71112"
xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option with PCI Express:</emphasis> If a
PCI Hot Plug DRC contains multiple PEs, then that DRC must be owned by
the platform or a trusted platform agent.</para>
<para>
<emphasis role="bold">Hardware implementation Notes:</emphasis>
<orderedlist>
<listitem>
<para>Surge current protection on the planar is one way to provide the
required protection against damage to components if an entity is removed
from or inserted into a connector with the power still applied to the
connector.</para>
</listitem>
<listitem>
<para>Removal of an entity without the proper quiescing operation may
result in a system crash.</para>
</listitem>
<listitem>
<para>In order for hot plugging of PCI plug-in cards with the system
operational to be useful, a mechanical means is needed in order to be
able to remove or insert PCI plug-in cards without shutting off system
power and without removing the covers above the plug-in cards (which in
general, would require powering-down the system).</para>
</listitem>
<listitem>
<para>It is recommended that the control of the indicators required by
Requirement
<xref linkend="dbdoclet.50569342_67003" /> be via the PCI Standard Hot
Plug Controller (see
<emphasis> <xref linkend="dbdoclet.50569387_87046" /> </emphasis>).</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569342_72553">
<title>PCI Hot Plug DR - Boot Time Firmware Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_72553"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> All OF requirements
of the base DR option architecture must be met (
<xref linkend="dbdoclet.50569342_82208" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_72553"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> The OF must only
generate the
<emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis> OF property for PCI
bridge nodes which cannot change bus clock frequency during a PCI Hot
Plug operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_72553"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> The OF must set the
PCI configuration register bits and fields appropriately.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis role="bold">Hardware Implementation Note:</emphasis> The OF should leave
sufficient gaps in the bus numbers when configuring bridges and switches
such that plug-in cards with bridges and switches which are to be
supported by the platform&#8217;s DR operations can be plugged into every
slot in the platform in which those plug-in cards are supported. That is,
insertion of an plug-in card that contains a bridge or switch into a
platform, requires that there be sufficient available bus numbers
allocated to that PCI bus such that new bus numbers can be assigned to
the buses generated by the bridges and switches on the plug-in
cards.</para>
</section>
<section xml:id="dbdoclet.50569342_67543">
<title>PCI Hot Plug DR - Run Time Firmware Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_67543"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> All RTAS requirements
of the base DR option architecture must be met (
<xref linkend="dbdoclet.50569342_40601" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_67543"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> The
<emphasis>set-indicator</emphasis> RTAS call with a indicator type of
isolation-state and a state value of unisolate (1) must not return a
&#8220;success&#8221; status until any IOA on a plug-in card inserted
into the PCI slot is ready to accept configuration cycles, and must
return a &#8220;success&#8221; status if the PCI slot is empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_67543"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> The
<emphasis>ibm,configure-connector</emphasis> RTAS call must initialize the
PCI configuration registers and platform to the same values as at boot
time.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> During a DR replace operation, the
replacement PCI IOA may not get placed back at the same addresses, etc.,
as the original DR entity by the firmware (although it has to be placed
back into the same DR connector, or it is not a DR replace operation). On
a replace operation, the configuration information cannot reliably be
read from the IOA being replaced (the IOA might be broken), so the
firmware cannot read the configuration information from the old IOA and
replace the configuration information into the new IOA.</para>
<para>PCI I/O sub-systems architecturally consist of two classes of
devices, bus bridges (Processor Host Bridges (PHBs), PCI to PCI Bridges,
and PCI Express switches and bridges) and IOAs. The support that
<emphasis>ibm,configure-connector</emphasis> provides for these two
classes is different.</para>
<para>For Bus Bridges, firmware will totally configure the bridge so that
it can probe down the depth of the tree. For this reason, the firmware
must include support for all bridges the platform supports. This includes
interrupt controllers as well as miscellaneous unarchitected devices that
do not appear in the OF device tree. The properties supported and
reported are the same as provided by the boot time firmware.</para>
<para>For PCI plug-in cards, the support is significantly less; it is
essentially the functionality specified in section 2.5 FCode Evaluation
Semantics of the
<xref linkend="dbdoclet.50569387_22451" />. However, the configuration
proceeds as if all devices do not have an expansion ROM since the RTAS
code does not attempt to determine if an FCode ROM is present nor
attempts to execute it. This may, in some cases, generate different
device node properties, values and methods than would happen had the IOA
been configured during boot. If the IOA&#8217;s device driver or
configuration support cannot deal with such differences, then the IOA is
not dynamically reconfigurable. The other properties generated are
dependent upon the IOA&#8217;s configuration header from the following
list. If the property is not on this list the reader should assume that
RTAS
<emphasis>ibm,configure-connector</emphasis> will not generate it.</para>
<para>
<xref linkend="dbdoclet.50569342_38602" /> shows what PCI OF properties
can be expected to be returned from the
<emphasis>ibm,configure-connector</emphasis> call for PCI Hot Plug
operations and
<xref linkend="dbdoclet.50569342_98892" /> shows some which can be
expected to not be returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_67543"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> The
<emphasis>ibm,configure-connector</emphasis> RTAS call when used for PCI
IOAs must return the properties named in
<xref linkend="dbdoclet.50569342_38602" /> except as indicated in the
Present?/Source column.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_38602">
<title>PCI Property Names which will be Generated by
<emphasis>ibm,configure-connector</emphasis></title>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Present?/Source</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. From PCI header.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. From PCI header.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. From PCI header.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. From PCI header.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present if Interrupt Pin register not 0.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;min-grant&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Present unless Header Type is 0x01.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;max-latency&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Present unless Header Type is 0x01.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;devsel-speed&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for conventional PCI and PCI-X.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. Constructed from the PCI header
information for the IOA or bridge.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;fast-back-to-back&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for conventional PCI and PCI-X when Status
Register bit 7 is set.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present if &#8220;Subsystem ID&#8221; register not
0.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present if &#8220;Subsystem vendor ID&#8221;
register not 0.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;66mhz-capable&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for conventional PCI and PCI-X when Status
Register bit 5 is set.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;133mhz-capable&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for PCI-X when PCI-X Status Register bit 17
is set.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;266mhz-capable&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for PCI-X when PCI-X Status Register bit 30
is set.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;533mhz-capable&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Only present for PCI-X when PCI-X Status Register bit 31
is set.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. Specifies address requirements.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;assigned-addresses&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. Specifies address assignment.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present. RTAS will have to remember the location
codes associated with all DR connectors so that it can build
this property.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Always present for sub-systems and for PCI IOAs which
follow the PCI VPD proposed standard. See
<!-- FIXME: Requirement R1-12.4.2-1-->
<xref linkend="dbdoclet.50569341_65980" /> and note to see the effect of
using different PCI versions.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>For bridges, always present with a value of
<emphasis role="bold"><literal>&#8220;PCI&#8221;</literal></emphasis> otherwise not
present.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,req#msi&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Present for all PCI Express IOA nodes which are
requesting MSI support, when the platform supports MSIs.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="dbdoclet.50569342_98892" /> is a non-exhaustive list of
common properties that may not be generated by RTAS
<emphasis role="bold"><literal>ibm,configure connector</literal></emphasis> for a PCI IOA. Also, the
concept of a phandle does not apply to nodes reported by
<emphasis role="bold"><literal>ibm,configure-connector</literal></emphasis>.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569342_98892">
<title>Non-exhaustive list of PCI properties that may not be
generated by
<emphasis>ibm,configure connector</emphasis></title>
<?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="35*" align="center" />
<colspec colname="c2" colwidth="65*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Present?/Source</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,connector-type&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- only for built-in entries not for
pluggable ones.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,wrap-plug-pn&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- only for built-in entries not for
pluggable ones.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;alternate-reg&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;fcode-rom-offset&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- RTAS does not look for this.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;wide&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;supported-network-types&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;address-bits&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;max-frame-size&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;local-mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;mac-address&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Never present -- needs FCode.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;built-in&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Not present for a PCI Hot Plug connectors.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis>Architecture Note</emphasis>: Without
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> and other properties, the
OS cannot append an IOA added via DR to the boot list for use during the
next boot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_67543"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug option:</emphasis> When
<emphasis>ibm,configure-connector</emphasis> RTAS call returns to the
caller, if the device driver(s) for any IOA(s) configured as part of the
call are EEH unaware (that is may produce data integrity exposures due to
an EEH stopped state) or if they may be EEH unaware, then the
<emphasis>ibm,configure-connector</emphasis> call must disable EEH prior
to returning to the caller.</para>
<para>
<emphasis role="bold">Software Implementation Note:</emphasis> To be EEH aware, a
device driver does not need to be able to recover from an EEH stopped
state, only recognize the all-1's condition and not use data from
operations that may have occurred since the last all-1's checkpoint. In
addition, the device driver under such failure circumstances needs to
turn off interrupts (using the
<emphasis>ibm,set-int-off</emphasis> RTAS call) in order to make sure that
any (unserviceable) interrupts from the IOA do not affect the system.
Note that this is the same device driver support needed to protect
against an IOA dying or against a no-DEVSEL type error (which may or may
not be the result of an IOA that has died). Note that if all-1&#8217;s
data may be valid, the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call should be used
to discover the true EEH state of the device.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_pci_hotplug">
<title>PCI Hot Plug DR - OS Requirements</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_pci_hotplug"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the PCI Hot Plug DR option:</emphasis> All OS requirements
of the base DR option architecture must be met (
<xref linkend="dbdoclet.50569342_16693" />).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569342_75053">
<title>Logical Resource Dynamic Reconfiguration (LRDR)</title>
<para>The Logical Resource Dynamic Reconfiguration option allows a platform
to make available and recover platform resources such as CPUs, Memory
Regions, Processor Host Bridges, and I/O slots to/from its operating OS
image(s). The Logical Resource Dynamic Reconfiguration option provides the
means for providing capacity on demand to the running OS and provides the
capability for the platform to make available spare parts (for example,
CPUs) to replace failing ones (called
<emphasis>sparing</emphasis> operations). Combined with the LPAR option,
platforms can move resources between partitions without rebooting the
partitions&#8217; OS images.</para>
<para>The Logical Resource Dynamic Reconfiguration (LRDR) option deals with
logical rather than physical resources. These logical resources are already
physically installed (dynamic installation/removal of these resources, if
supported, is managed via the Hardware Management Console (HMC) or Service
Focal Point (SFP)). As such, the OS does not manage either connector power
or DR visual indicators. Logical connector power domains are specified as
&#8220;hot pluggable&#8221; (value -1) and DR visual indicators are not
defined for logical connectors.</para>
<para>The device tree contains logical resource DR connectors for the
maximum number of resources that the platform can allocate to the specific
OS. In some cases such as for processors and PHBs, this may be the maximum
number of these resources that the platform supports even if there are
fewer than that currently installed. In other cases, such as memory regions
in a LPARed system, the number may be limited to the amount of memory that
can be supported without resizing the cpu page frame table. The OS may use
the
<emphasis>get-sensor-state</emphasis> RTAS call with the dr-entity-sense
token to determine if a given drc-index refers to a connector that is
currently usable for DR operations. If the connector is not currently
usable the return state is &#8220;DR entity unusable&#8221; (2). A
<emphasis>set-indicator</emphasis> (isolation state) RTAS call to an
unusable connector or (dr-indicator) to any logical resource connector
results in a &#8220;No such indicator implemented&#8221; return
status.</para>
<para>Two allocation models are supported. In the first, resources are
specifically assigned to one and only one partition at a time by the HMC.
In this model, a DR entity state is changed from unusable to usable only by
firmware in response to HMC requests to explicitly move the allocation of
the resource between partitions. In the second model, certain resources may
&#8220;float&#8221; between cooperating partitions, a partition issues a
<emphasis>set-indicator</emphasis> (allocation state usable) RTAS call and
if the resource is free, the firmware assigns the resource to the
requesting partition and returns the success status.
<emphasis>Set-indicator</emphasis> returns the code
&#8220;no-such-indicator&#8221; if either the resource is not free, or the
platform is operating in the first model. To return a resource to the
platform firmware, the OS issues a
<emphasis>set-indicator</emphasis> (allocation state unusable) RTAS call for
the resource&#8217;s DR connector.</para>
<section xml:id="sec_platform_req_lrdr">
<title>Platform Requirements for LRDR</title>
<para>The following requirements apply to the hardware and/or firmware as
a result of implementing LRDR on a platform.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_platform_req_lrdr"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The hardware must provide the
capability to power-cycle any hardware that is going to be switched
between partitions as part of LRDR, if that hardware requires
power-cycling to put the hardware into a known state (for example, PCI
IOAs).</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> Except for PCI Express IOAs that
implement the Function Level Reset (FLR) option, since the PCI
architecture is not specific as to the state of the IOA when the IOAs
reset is activated and deactivated, either the platform designer will
need to guarantee that all logic in all IOAs (including any internal
storage associated with the IOA) is cleared to a known state by use of
the IOAs' reset, or else the platform will need to provide the capability
to power-cycle those IOAs, including the integrated ones (that is,
including the non-pluggable ones). Also note that hardware which requires
power-cycling to initialize may impact the capability to reliably reboot
an OS, independent of whether or not LRDR is implemented.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_52827">
<term><emphasis role="bold">R1-<xref linkend="sec_platform_req_lrdr"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis>
Any power-cycling
of the hardware which is done by the platform during an LRDR operation
(for example, as part of an ibm,configure-connector operation), must be
functionally transparent to the software, except that PCI plug-in cards
that are plugged into a PCI Hot Plug DR connector do not need to be
powered on before the
<emphasis>ibm,configure-connector</emphasis> call for a logical SLOT DR
connector returns to the caller.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> PCI plug-in cards that are plugged
into a DR connector will not be configured as part of an
ibm,configure-connector operation on a logical DR connector of type SLOT
above the plug-in card (see section 17.6.3.3 ibm,configure-connector).
However, Requirement
<xref linkend="dbdoclet.50569342_52827" /> does require a PCI IOA which is
not plugged in to a PCI Hot Plug DR connector (for example, soldered on
the planar) be powered up and configured as a result of an
ibm,configure-connector operation on a logical DR connector of type SLOT
above such an IOA, and requires this powering up to be functionally
transparent to the caller of ibm,configure-connector operation (a longer
busy time is not considered to be a violation of the functional
transparency requirement).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_dr_prop">
<title>DR Properties for Logical Resources</title>
<para>Logical resource dynamic reconfiguration is a special case of
general DR, therefore, certain DR properties take on special
values.</para>
<table frame="all" pgwide="1">
<title>DR Property Values for Logical Resources</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="35*" />
<colspec colname="c2" colwidth="65*" />
<thead>
<row>
<entry align="center">
<para>
<emphasis role="bold">Property Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Property Value</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>As defined in
<xref linkend="dbdoclet.50569342_17435" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>As defined in
<xref linkend="dbdoclet.50569342_31379" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>As defined in
<xref linkend="dbdoclet.50569342_22748" />.<?linebreak?>
<emphasis role="bold">Note:</emphasis>
This name
allows for correlation between the OS and HMC user
interfaces.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Logical Resource connectors are defined to be &#8220;hot
pluggable&#8221; having a domain value of -1 per definition in
<xref linkend="dbdoclet.50569342_86369" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Shall be one of the values &#8220;CPU&#8221;,
&#8220;MEM&#8221;, &#8220;PHB&#8221;, or &#8220;SLOT&#8221; as
defined in
<xref linkend="dbdoclet.50569368_97022" />.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>As defined in
<xref linkend="sec_ibmdrcinfo_property" />.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> All platform requirements of the
base DR option architecture must be met (
<xref linkend="dbdoclet.50569342_98936" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The
<emphasis role="bold"><literal>/cpus</literal></emphasis> OF device tree node must include
either the <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property or the following four properties:
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>.
The drc-type must be type CPU, and the drc-power-domain must have the value -1. The
property or properties must contain entries for each potentially supported dynamically reconfigurable processor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The root node of the OF device
tree must include
ither the <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property or the following four properties:
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>.
The drc-type must be type MEM and the drc-power-domain must have the value -1.
The property or properties must contain entries for each potentially supported dynamically
reconfigurable memory region.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The root node of the OF device
tree must not include any drc properties (
<emphasis role="bold"><literal>&#8220;ibm,drc-*&#8221;</literal></emphasis>) for the base memory region
(reg value 0).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The root node of the OF device
tree must include
either the <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property or the following four properties:
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>.
The drc-type must be type PHB, and the drc-power-domain must have the value -1.
The property or properties must contain entries for each potentially supported dynamically
reconfigurable PHB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The
<emphasis role="bold"><literal>/pci</literal></emphasis> OF device tree node representing a PHB must
include
either the <emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property or the following four properties:
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>.
The drc-type must be type SLOT, and the drc-power-domain must have the value -1.
The property or properties must contain entries for each potentially supported dynamically
reconfigurable PCI SLOT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> platforms must implement the
allocation-state indicator 9003, as defined in
<xref linkend="dbdoclet.50569342_34333" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_dr_prop"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> For memory LRDR, the
<emphasis role="bold"><literal>&#8220;ibm,lrdr-capacity&#8221;</literal></emphasis> property must be
included in the
<emphasis role="bold"><literal>/rtas</literal></emphasis> node of the partition device tree (see
<xref linkend="dbdoclet.50569368_41461" />).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Architectural Intent -- Logical DR Sequences:</title>
<para>This architecture is designed to support the logical DR sequences
specified in the following sections. See also
<xref linkend="dbdoclet.50569342_69828" />.</para>
<section>
<title>Acquire Logical Resource from Resource Pool</title>
<orderedlist>
<listitem>
<para>The OS responds to some stimuli (command, workload manager, HMC,
etc.) to acquire the resource, perhaps using the
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> value as a reference if a
human interface is involved.</para>
</listitem>
<listitem>
<para><!--anchor xml:id="dbdoclet.50569342_28284" /-->The OS determines
if the resource is usable:</para>
<orderedlist>
<listitem>
<para>OS uses
<emphasis>get-sensor-state</emphasis> (dr-entity-sense) to determine the
state of the DR connector</para>
</listitem>
<listitem>
<para>If the state is &#8220;unusable&#8221; the OS issues
<emphasis>set-indicator</emphasis> (allocation-state, usable) to attempt
to allocate the resource. Similarly, if the state is &#8220;available for
exchange&#8221; the OS issues
<emphasis>set-indicator</emphasis> (allocation-state, exchange) to attempt
to allocate the resource, and if the state is &#8220;available for
recovery&#8221; the OS issues
<emphasis>set-indicator</emphasis> (allocation-state, recover) to attempt
to allocate the resource.</para>
</listitem>
<listitem>
<para>If successful, continue, else return error status to the
requester. If successful, this is the point where the resource is
allocated to the OS.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Continue with DR operation.</para>
<orderedlist>
<listitem>
<para>The OS unisolates the resource via
<emphasis>set-indicator</emphasis> (isolation-state, unisolate). This is
the point where the OS takes ownership of the resource from the platform
firmware and the firmware removes the resource from its resource
pool.</para>
</listitem>
<listitem>
<para>The OS configures the resource using
<emphasis>ibm,configure-connector</emphasis> RTAS.</para>
</listitem>
<listitem>
<para>The OS incorporates the resource into its resource pool.</para>
<orderedlist>
<listitem>
<para>If the resource is a processor, the OS must use the
<emphasis>start-cpu</emphasis> RTAS call to move the processor from the
stopped state (at the end of the
<emphasis>ibm,configure-connector</emphasis>) to the running
state.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>The OS returns status of operation to the requester.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>The OS notifies requesting entity of the OS state relative to
the resource acquisition.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Release Logical Resource</title>
<orderedlist>
<listitem>
<para>Some entity (System administrator commanding from the HMC, a
workload manager, etc.) requests the OS to release the resource using the
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis> value as a
reference.</para>
<orderedlist>
<listitem>
<para>The OS attempts to stop using logical resource.</para>
<orderedlist>
<listitem>
<para>If the resource is a processor, the OS calls the
<emphasis>stop-self</emphasis> RTAS call then waits for the processor to
enter the stopped state using the RTAS
<emphasis>query-cpu-stopped-state</emphasis> call.</para>
</listitem>
<listitem>
<para>The OS isolates the resource via
<emphasis>set-indicator</emphasis> (isolation-state, isolate).</para>
</listitem>
<listitem>
<para>Unless the isolated resource was the partition&#8217;s last
processor, the OS deallocates the resource via
<emphasis>set-indicator</emphasis> (allocation-state, unusable). This is
the point where the platform firmware takes ownership of the resource
from the OS. That is, the OS removes the resource from its resource pool
and the firmware adds it to the firmware resource pool.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>The OS returns status of operation to the requester.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>The OS unallocates the resource by
<emphasis>set-indicator</emphasis> (allocation-state, unusable).</para>
</listitem>
<listitem>
<para>The system administrator may command the HMC to allocate the
logical resource to another partition (LPAR) or reserved pool
(COD).</para>
</listitem>
<listitem>
<para>Any needed hardware removal is handled by HMC/SPC.</para>
</listitem>
</orderedlist>
</section>
</section>
<section>
<title>RTAS Call Semantics/Restrictions</title>
<para>This section describes the unique application of DR RTAS functions
to the dynamic reconfiguration of logical resources.</para>
<section>
<title><emphasis>set-indicator</emphasis> (isolation-state, isolate)</title>
<para>Dynamic reconfiguration of logical resources introduces special
meaning and restrictions to the DR connector isolation function depending
upon the logical resource being isolated.</para>
<section xml:id="sec_cpu_isolation">
<title>Isolation of CPUs</title>
<para>The isolation of a CPU, in all cases, is preceded by the
<emphasis>stop-self</emphasis> RTAS function for all processor threads,
and the OS insures that all the CPU&#8217;s threads are in the RTAS
stopped state prior to isolating the CPU. Isolation of a processor that
is not stopped produces unpredictable results. The stopping of the last
processor thread of a LPAR partition effectively kills the partition, and
at that point, ownership of all partition resources reverts to the
platform firmware.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_cpu_isolation"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> Prior to issuing the RTAS
<emphasis>set-indicator</emphasis> specifying isolate isolation-state of a
CPU DR connector type, all the CPU threads must be in the RTAS stopped
state.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_cpu_isolation"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> Stopping of the last processor
thread of a LPAR partition with the
<emphasis>stop-self</emphasis> RTAS function, must kill the partition,
with ownership of all partition resources reverting to the platform
firmware.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_mem_isolation">
<title>Isolation of MEM Regions</title>
<para>Isolation of a MEM region creates a paradox if the MEM region being
isolated contains the calling program (there being no program left for
the firmware to return).</para>
<para>
<emphasis role="bold">Note:</emphasis> The base memory region (starting at address
zero) is not associated with a MEM DR connector. This means that the base
memory region cannot be isolated. This restriction avoids two fatal
conditions, attempts to isolate the region containing RTAS, and attempts
to isolate the region containing the interrupt vectors.</para>
<para>It is the responsibility of the OS to unmap the addresses of the
MEM region being isolated from both PFT and the TCE tables. When the LRDR
option is combined with the LPAR option, the hypervisor ensures that the
addresses of the MEM region being isolated are unmapped from both the PFT
and TCE tables before successfully completing the isolation of the MEM
region. If any valid mappings are found, the RTAS
<emphasis>set-indicator</emphasis> (isolation-state) does not change the
isolation-state and returns with a
<emphasis>Status</emphasis>-9001 (Valid outstanding translation).</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_mem_isolation"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option:</emphasis> The caller of the RTAS
<emphasis>set-indicator</emphasis> specifying isolate isolation-state of a
MEM DR connector type must not be within the region being
isolated.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="dbdoclet.50569342_16782">
<term><emphasis role="bold">R1-<xref linkend="sec_mem_isolation"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option combined with the LPAR option:</emphasis>
The RTAS <emphasis>set-indicator</emphasis> specifying isolate isolation-state of a
MEM DR connector type must check that the region is unmapped from both
the partition&#8217;s Page Frame Table(s) and any Translation Control
Entries that would reference the memory, else the RTAS routine must
return with a status of
<emphasis>Status</emphasis>-9001 (Valid outstanding translation) and the
isolation-state is not changed.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis role="bold">Implementation Note:</emphasis> The algorithm chosen for
implementing Requirement
<xref linkend="dbdoclet.50569342_16782" /> depends upon the expected
frequency of isolation events. For RAS reasons, they should be seldom.
For load balancing, they may be far more frequent. These methods are
briefly described here:</para>
<itemizedlist>
<listitem>
<para>First pull the corresponding logical address from the
partition&#8217;s valid space so setting new translations to the logical
address are not possible. Then wait for any current in flight translation
additions to complete. Followed by either scanning the entire PFT and TCE
tables looking for valid translations or checking a use count for the
particular logical address range. The PFT/TCE table search may be long,
however, it is only done at isolation time.</para>
</listitem>
<listitem>
<para>The use count method must be maintained for each add and remove
of an address translation with the corresponding accessing of a use count
based upon the physical real address of the memory block.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50569342_11827">
<title>Isolation of PHBs and Slots</title>
<para>An isolation of a PHB naturally disconnects the OS image from any
of the DR connectors downstream of the PHB (specifically any I/O slots
and PCI Hot Plug connectors associated with the PHB). To avoid the
complexity of gracefully managing multi-level isolation, isolation is
restricted to only &#8220;leaf&#8221; DR connectors, that is connectors
that have no unisolated or usable DR connectors below them. That is, for
logical DR connectors below the connector being isolated, a
<emphasis>get-sensor-state</emphasis> dr-entity-sense needs to return an
unusable (2) and for physical DR connectors below the connector being
isolated, the DR entity needs to be isolated first via
<emphasis>set-indicator</emphasis> (isolation-state, isolate). The OS is
responsible for removing all virtual address mappings to the address
range associated with a logical I/O SLOT before making the RTAS
<emphasis>set-indicator</emphasis> (isolation-state) call that isolates
the SLOT. When the LRDR option is combined with the LPAR option, the
hypervisor ensures that the addresses associated with the logical SLOT
being isolated are unmapped from both the PFT and TCE tables before
successfully completing the isolation of the SLOT connector. If any valid
mappings are found, the RTAS
<emphasis>set-indicator</emphasis> (isolation-state) does not change the
isolation-state and returns with a
<emphasis>Status</emphasis>-9001 (Valid outstanding translation).</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_11827"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>set-indicator</emphasis> (isolation-state, isolate) would result
in the isolation of one or more other DR connectors which are currently
unisolated or usable, then the
<emphasis>set-indicator</emphasis> RTAS must fail with a return code of
&#8220;Multi-level isolation error&#8221; (-9000).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569342_11827"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option combined with the LPAR
option:</emphasis> The RTAS
<emphasis>set-indicator</emphasis> specifying isolate isolation-state of a
SLOT DR connector type must check that the IOA address range associated
with the slot is unmapped from both the partition&#8217;s Page Frame
Table(s) and any Translation Control Entries that would reference those
locations, else the RTAS routine must return with a
<emphasis>Status</emphasis>-9001 (Valid outstanding translation) and the
isolation-state is not changed.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_isolation_of_coherent_platform_facilities">
<title>Isolation of Coherent Platform Facilities</title>
<para>Isolation of a Coherent Platform Facility (COPLATFAC) disconnects the OS
image from any of the DR connectors downstream (Coherent Platform Functions or
COPLATFUN) of the Coherent Platform Facility. To avoid the complex- ity of
gracefully managing multi-level isolation, isolation is restricted to only
“leaf” DR connectors, that is connectors that have no unisolated or usable DR
connectors below them. All COPLATFUN connectors must return unusable state (2)
during get-sensor-state before a COPLATFAC can be isolated, this is done through
set-indicator (isolation-state, isolate). The OS is responsible for removing all
memory mappings and detaching all processes potentially in use by co- herent
platform functions. If valid mappings or processes are found, the set-indicator
does not change the isolation state and returns with a Status -9001 (Valid
outstanding translation).</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_isolation_of_coherent_platform_facilities"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a
request to <emphasis>set-indicator</emphasis> (isolation-state, isolate)
would result in the isolation of one or more other DR connectors
which are currently unisolated or usable, then the
<emphasis>set-indicator</emphasis> RTAS must fail with a return code of
“Multi-level isolation error” (-9000).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_isolation_of_coherent_platform_facilities"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For the LRDR option combined with the LPAR
option:</emphasis> The RTAS <emphasis>set-indicator</emphasis> specifying
isolate isolation-state of a COPLATFUN DR connector type must check that
all processes associated with the function are detached, else the RTAS
routine must return with a Status -9001 (Valid outstanding translation)
and the isolation-state is not changed.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="sec_set_indicator">
<title><emphasis>set-indicator</emphasis> (dr-indicator)</title>
<para>Logical connectors do not have associated dr-indicators (token
value 9002). An attempt to set the state of such an indicator results in
a &#8220;No such indicator implemented&#8221; return status.
</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_set_indicator"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> The calling of
<emphasis>set-indicator</emphasis> with a token value of 9002
(dr-indicator) and an index representing a logical connector must fail
with a return code of &#8220;No such indicator implemented&#8221;
(-3).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec_ibm_configure_connnector">
<title><emphasis>ibm,configure-connector</emphasis></title>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call is used to return
to the OS the device tree nodes and properties associated with the newly
un-isolated logical resources and configure them for use.</para>
<para>The
<emphasis>ibm,configure-connector</emphasis> RTAS call used against a
logical DR connector can encounter other logical DR connectors or
physical DR connectors below it in the tree. If a logical connector is
encountered below a logical connector that is being configured, the
<emphasis>ibm,configure-connector</emphasis> RTAS call will not configure
the sub-tree, if it is not owned by the OS (where owned refers to a DR
connector that would return a DR entity usable, for a
<emphasis>get-sensor</emphasis> dr-entity-sense sensor). If a physical
connector is encountered, then the sub-tree below the physical connector
may or may not be configured, depending on the implementation.</para>
<para>
<emphasis role="bold">Architecture Note:</emphasis> The requirements of this section
specify the minimum sub-tree contents returned for various connector
types. Implementations may optionally return other valid previously
reported nodes that represent the current configuration of the device
tree. Previously reported nodes may not have any changes from their
previously reported state. A node that was removed from the configuration
due to a DR operation and returns due to a subsequent DR operation is not
considered to have been previously reported. It is the caller's
responsibility to recognize previously reported nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector that is
isolated,
<emphasis>ibm,configure-connector</emphasis> must immediately return
configuration complete.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If the connector index refers
to a connector that would return a &#8220;DR entity unusable&#8221;
status (2), &#8220;DR entity available for exchange&#8221; status (3), or
&#8220;DR entity available for recovery&#8221; status (4) to the
<emphasis>get-sensor</emphasis> dr-entity-sense token, the
<emphasis>ibm,configure-connector</emphasis> RTAS call must return
&#8220;-9003: Cannot configure - Logical DR connector unusable, available
for exchange, or available for recovery&#8221; on the first call without
any configuration action taken on the DR connector.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector of type
CPU,
the returned sub-tree must consist of the specific
cpu-node, its children, and any referenced nodes that had not been
previously reported (such as L2 and L3 caches etc.) all containing the
properties as would be contained in those nodes had they been available
at boot time.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> Future platforms that support
concurrent maintenance of caches, will require that high level cache
nodes (L2, L3 etc.) are added by
<emphasis>ibm,configure-connector</emphasis> such that their properties
can change as new/repaired hardware is added to the platform. Therefore,
it is the OS's responsibility when isolating a CPU to purge any
information it may have regarding an orphaned high level cache node. The
OS may use the
<emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis> property to selectively
remove caches when a processor is removed. The platform considers any
high level cache that is newly referenced (reference count for this
partition goes from 0 to 1) to have been previously unreported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis role="bold"><literal>ibm,configure-connector</literal></emphasis> specifies a connector of type
MEM,
the returned sub-tree must consist of the specific
<emphasis role="bold"><literal>ibm,memory-region</literal></emphasis> node containing the properties as
would be contained in that node had it been available at boot
time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector of type
PHB or SLOT, then all of the following must be true:
<orderedlist numeration="loweralpha">
<listitem>
<para>The returned values must represent the sub-tree for the specific
I/O sub-system represented by the connector, except for entities below
any DR connectors (logical or physical) which are below the connector
which is the target of the ibm,configure-connector operation (that is,
the ibm,configure-connector operation stops at any DR connector).</para>
</listitem>
<listitem>
<para>The sub-tree must consist of the specific node and its children
all containing the properties as would be contained in those nodes had
they been available at boot time, including (if they exist) built-in PCI
IOAs.</para>
</listitem>
</orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector of type
SLOT,
the returned values must represent the sub-tree for
the specific I/O sub-system represented by the SLOT connector, and the
sub-tree must consist of the specific
<emphasis role="bold"><literal>/pci</literal></emphasis> node and its children all containing the
properties as would be contained in those nodes had they been available
at boot time, except for the PCI IOA nodes assigned to the OS image that
contain the same properties as they would following a PCI hot plug
operation (see
<xref linkend="dbdoclet.50569342_67543" />).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a platform implementation
powers-up and configures physical DR entities in the sub-tree under a
logical DR connector, then a request to
<emphasis>ibm,configure-connector</emphasis> of the logical DR connector
must use the return status of 990x from the
<emphasis>ibm,configure-connector</emphasis> call, as necessary, during
the DR entity power-up sequence(s) and must control any power-up and
sequencing requirements, as would be done by the platform during platform
power-up.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">R1-<xref linkend="sec_ibm_configure_connnector"
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
<listitem>
<para><emphasis role="bold">For all LRDR options:</emphasis> If a request to
<emphasis>ibm,configure-connector</emphasis> specifies a connector of
type CO- PLATFAC or COPLATFUN, the returned values must represent the
sub-tree for the specific coherent plat- form sub-system represented by
the COPLATFAC or COPLATFUN connector. All properties are updated with
the most recent data from the coherent platform resource.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
</chapter>
Reference in New Issue View Git Blame Copy Permalink