diff --git a/DeviceTree/ch_devtree_system.xml b/DeviceTree/ch_devtree_system.xml
index eaa1e08..ab32cfa 100644
--- a/DeviceTree/ch_devtree_system.xml
+++ b/DeviceTree/ch_devtree_system.xml
@@ -4625,6 +4625,22 @@
+
+ “ibm,current-associativity-domains”
+
+ property name to define the current number of associativity domains
+ for this platform.
+ prop-encoded-array: An associativity list such that all values
+ are the number of unique values that the current platform supports in that location.
+ The associativity list consisting of a number of entries integer (N) encoded as with
+ encode-int
+ followed by N integers encoded as with
+ encode-int
+ each representing
+ current number of unique asso- ciativity domains the platform supports at that level.
+
+
+
“ibm,request-partition-shutdown”
diff --git a/Platform/ch_numa.xml b/Platform/ch_numa.xml
index cac8904..e813542 100644
--- a/Platform/ch_numa.xml
+++ b/Platform/ch_numa.xml
@@ -1,62 +1,62 @@
-Non Uniform Memory Access (NUMA) Option
-
+
Summary of Extensions to Support NUMA
- NUMA platforms to a first level approximation are simply a large
- scale Symmetric Multi-Processor. However to tune system performance and to aid
- in platform maintenance, the OS needs additional information and mechanisms.
+ NUMA platforms to a first level approximation are simply a large
+ scale Symmetric Multi-Processor. However to tune system performance and to aid
+ in platform maintenance, the OS needs additional information and mechanisms.
These include:
-
+
- Associativity -- to determine the platform resource
+ Associativity -- to determine the platform resource
groupings.
-
+
- Relative Performance Distances -- to determine the performance
+ Relative Performance Distances -- to determine the performance
between resources within different groupings.
-
+
- Performance Monitor -- to provide usage data on the NUMA
+ Performance Monitor -- to provide usage data on the NUMA
fabric.
-
+
- Dynamic Reconfiguration -- due to such causes as platform upgrade,
+ Dynamic Reconfiguration -- due to such causes as platform upgrade,
reallocation of resources, or a repair of a failure.
-
+
- There are two NUMA support options: the “NUMA” option
- and its proper subset the “Associativity Information”
+ There are two NUMA support options: the “NUMA” option
+ and its proper subset the “Associativity Information”
option.
-
+
NUMA Resource Associativity
- Associativity Codes represent the groupings of the various platform
- resources into domains of substantially similar mean performance relative to
- resources outside of that domain. Resources subsets of a given domain that
- exhibit better performance relative to each other than relative to other
- resources subsets, are represented as being members of a sub-grouping domain.
- Such sub-domain grouping is represented to any level deemed significant by the
- platform design. presents a simple
- system configuration with one possible decomposition into associativity
- domains. From the decomposition provided the
- “ibm,associativity” value string for each resource is
+ Associativity Codes represent the groupings of the various platform
+ resources into domains of substantially similar mean performance relative to
+ resources outside of that domain. Resources subsets of a given domain that
+ exhibit better performance relative to each other than relative to other
+ resources subsets, are represented as being members of a sub-grouping domain.
+ Such sub-domain grouping is represented to any level deemed significant by the
+ platform design. presents a simple
+ system configuration with one possible decomposition into associativity
+ domains. From the decomposition provided the
+ “ibm,associativity” value string for each resource is
enumerated.
-
- The OF Device Tree node for each allocable resource
- (processor, memory region, and IO slot) conveys information about the resources
- statically assigned to the client program; and contains the
- “ibm,associativity”
- property (see ). This property allows the client
- program to determine the associativity between any two of it’s
- resources. The greater the associativity the greater the expected performance
+
+ The OF Device Tree node for each allocable resource
+ (processor, memory region, and IO slot) conveys information about the resources
+ statically assigned to the client program; and contains the
+ “ibm,associativity”
+ property (see ). This property allows the client
+ program to determine the associativity between any two of it’s
+ resources. The greater the associativity the greater the expected performance
when using those two resources in a given operation.
- The legal form of the “ibm,associativity”
- property is dependent upon the setting of the
- “ibm,architecture-vec-5”
- property byte 5 bit 0. The bit value of zero allows the
- “ibm,associativity” property string to be sequenced in
- priority order; this form is being deprecated for new implementations in favor
- of the form indicated by the
+ The legal form of the “ibm,associativity”
+ property is dependent upon the setting of the
“ibm,architecture-vec-5”
- property byte 5 bit 0 having the value of one in which the
- “ibm,associativity” property string represents the
+ property byte 5 bit 0. The bit value of zero allows the
+ “ibm,associativity” property string to be sequenced in
+ priority order; this form is being deprecated for new implementations in favor
+ of the form indicated by the
+ “ibm,architecture-vec-5”
+ property byte 5 bit 0 having the value of one in which the
+ “ibm,associativity” property string represents the
strict physical hierarchy of the platform.
- When the LPAR option is also implemented, the partition virtual
- resources may be mapped onto physical resources with in a very dynamic manor.
- Given that the resource mapping to the associativity domain is substantially
- consistent, the client program can make use of the associativity information to
- on the average optimize performance. If the resource mapping to the
- associativity domain is substantially inconsistent, then associativity
- information for the resources is not provided to prevent erroneous operation.
- If the long term mapping changes the client program can be made aware of the
- new associativity information using the ibm,update-properties RTAS call (See
+ When the LPAR option is also implemented, the partition virtual
+ resources may be mapped onto physical resources with in a very dynamic manor.
+ Given that the resource mapping to the associativity domain is substantially
+ consistent, the client program can make use of the associativity information to
+ on the average optimize performance. If the resource mapping to the
+ associativity domain is substantially inconsistent, then associativity
+ information for the resources is not provided to prevent erroneous operation.
+ If the long term mapping changes the client program can be made aware of the
+ new associativity information using the ibm,update-properties RTAS call (See
).
- R1-R1--1.
- For the NUMA or Associativity
- Information option: The platform must include the
- “ibm,associativity” in the OF device tree
- memory node and the nodes of each processor, memory
- region, and PCI bridge onto which IOAs may be plugged if the component is
- dedicated to the partition. (The device tree node for a component that the
- platform intends to virtualize should include an
- “ibm,associativity” property if the associativity
+ For the NUMA or Associativity
+ Information option: The platform must include the
+ “ibm,associativity” in the OF device tree
+ memory node and the nodes of each processor, memory
+ region, and PCI bridge onto which IOAs may be plugged if the component is
+ dedicated to the partition. (The device tree node for a component that the
+ platform intends to virtualize should include an
+ “ibm,associativity” property if the associativity
domain information is substantially accurate.)
-
+
- R1-R1--2.
- For the NUMA option and SPLPAR
- option: In the case that both the NUMA and SPLPAR options are
- implemented, Requirement is modified
- to remove processors from the list of system elements that must include the
- respective properties or interfaces described by that requirement. (The
- platform is encouraged to provide processor associativity information if it is
+ For the NUMA option and SPLPAR
+ option: In the case that both the NUMA and SPLPAR options are
+ implemented, Requirement is modified
+ to remove processors from the list of system elements that must include the
+ respective properties or interfaces described by that requirement. (The
+ platform is encouraged to provide processor associativity information if it is
substantially accurate.)
- The “ibm,associativity”
- property contains one or more lists of numbers representing the
- resource’s platform grouping domains. Each list, starts with a number
- representing the domain number of the highest level grouping within which the
- platform is capable of supporting direct access. This highest level may be a
- NUMA collective or possibly a cluster of machines with direct DMA access.
- Successive numbers represent sub-divisions of the previous higher level within
- which the expected mean value of the performance relative to outside resources
- is substantially similar. Implementations determine the number of levels that
- they report, subject to Requirements
- and . The lowest level always being
- that of the allocable resource itself. The user of this information is
- cautioned not to imply any specific physical/logical significance of the
+ The “ibm,associativity”
+ property contains one or more lists of numbers representing the
+ resource’s platform grouping domains. Each list, starts with a number
+ representing the domain number of the highest level grouping within which the
+ platform is capable of supporting direct access. This highest level may be a
+ NUMA collective or possibly a cluster of machines with direct DMA access.
+ Successive numbers represent sub-divisions of the previous higher level within
+ which the expected mean value of the performance relative to outside resources
+ is substantially similar. Implementations determine the number of levels that
+ they report, subject to Requirements
+ and . The lowest level always being
+ that of the allocable resource itself. The user of this information is
+ cautioned not to imply any specific physical/logical significance of the
various intermediate levels.
-
+
- R1-R1--3.
- For the NUMA or Associativity
- Information option: Differing levels of resource grouping represented in the
- “ibm,associativity” property
- must reflect statistically repeatable differences in the expected mean of
+ For the NUMA or Associativity
+ Information option: Differing levels of resource grouping represented in the
+ “ibm,associativity” property
+ must reflect statistically repeatable differences in the expected mean of
measured performance.
-
+
- R1-R1--4.
- For the NUMA or Associativity
- Information option: The expected mean performance of any resource
- of a given type within the same grouping domain represented in the
- “ibm,associativity” property relative to
+ For the NUMA or Associativity
+ Information option: The expected mean performance of any resource
+ of a given type within the same grouping domain represented in the
+ “ibm,associativity” property relative to
resources outside of that grouping domain must be substantially similar.The reason that the “ibm,associativity”
- property may contain
- multiple associativity lists is that a resource may be multiply connected into
- the platform. This resource then has a different associativity characteristics
- relative to its multiple connections. To determine the associativity between
- any two resources, the OS scans down the two resources associativity lists in
- all pair wise combinations counting how many domains are the same until the
- first domain where the two list do not agree. The highest such count is the
+ property may contain
+ multiple associativity lists is that a resource may be multiply connected into
+ the platform. This resource then has a different associativity characteristics
+ relative to its multiple connections. To determine the associativity between
+ any two resources, the OS scans down the two resources associativity lists in
+ all pair wise combinations counting how many domains are the same until the
+ first domain where the two list do not agree. The highest such count is the
associativity between the two resources.
-
+
Relative Performance Distance
- An OS applies its NUMA tuning techniques based upon associativity and
- relative performance distance attributes. As a guide to relative performance
- distance, RISC Platforms provide the “ibm,associativity-reference-points”
- property. The information in this property represents a first order approximation to points
- having associativity and relative performance distance characteristics deemed
+ An OS applies its NUMA tuning techniques based upon associativity and
+ relative performance distance attributes. As a guide to relative performance
+ distance, RISC Platforms provide the “ibm,associativity-reference-points”
+ property. The information in this property represents a first order approximation to points
+ having associativity and relative performance distance characteristics deemed
to be of significant interest to optimizing client program performance.
- The contents of the “ibm,associativity-reference-points”
- property is dependent upon the setting of the
- “ibm,architecture-vec-5”
- property byte 5 bit 0. The bit value of zero allows the
- “ibm,associativity-reference-points” property string
- to indicate logical structure points; this form is being deprecated for new
- implementations in favor of the form indicated by the
- “ibm,architecture-vec-5”
- property byte 5 bit 0 having the value of one in which the
- “ibm,associativity-reference-points” property string
- represents boundaries between associativity domains presented by the
- “ibm,associativity” property containing
+ The contents of the “ibm,associativity-reference-points”
+ property is dependent upon the setting of the
+ “ibm,architecture-vec-5”
+ property byte 5 bit 0. The bit value of zero allows the
+ “ibm,associativity-reference-points” property string
+ to indicate logical structure points; this form is being deprecated for new
+ implementations in favor of the form indicated by the
+ “ibm,architecture-vec-5”
+ property byte 5 bit 0 having the value of one in which the
+ “ibm,associativity-reference-points” property string
+ represents boundaries between associativity domains presented by the
+ “ibm,associativity” property containing
“near” and “far” resources.
- R1-R1--1.
- For the NUMA or Associativity
- Information option: The RTAS OF device tree node must contain the
+ For the NUMA or Associativity
+ Information option: The RTAS OF device tree node must contain the
“ibm,associativity-reference-points”.
-
+
Form 0When the “ibm,architecture-vec-5”
- property byte 5 bit 0 has the value of zero, the
- “ibm,associativity-reference-points” property defines
- reference points in the “ibm,associativity”
- property (see ) which roughly correspond to
- traditional notions of platform topology constructs. It is important for the
- user to realize that these reference points are not exact and their
+ property byte 5 bit 0 has the value of zero, the
+ “ibm,associativity-reference-points” property defines
+ reference points in the “ibm,associativity”
+ property (see ) which roughly correspond to
+ traditional notions of platform topology constructs. It is important for the
+ user to realize that these reference points are not exact and their
characteristics vary among implementations.
- The first integer in the “ibm,associativity-reference-points”
- property relates the 1 based ordinal in the associativity lists of the platform’s
- “ibm,associativity” property associated
- with the traditional notion of a symmetric multi-processor within a NUMA
- platform. That is the level that represents building blocks of processors and
+ The first integer in the “ibm,associativity-reference-points”
+ property relates the 1 based ordinal in the associativity lists of the platform’s
+ “ibm,associativity” property associated
+ with the traditional notion of a symmetric multi-processor within a NUMA
+ platform. That is the level that represents building blocks of processors and
memory that have the following characteristics:
-
+
- An OS is likely to view all members having roughly uniform access
+ An OS is likely to view all members having roughly uniform access
characteristics.
-
+
- Represents the highest level before an OS is likely to notice
+ Represents the highest level before an OS is likely to notice
major Non-Uniformity of access.
-
-
- The second integer in the “ibm,associativity-reference-points”
- property relates the 1 based ordinal in the associativity lists of the platform’s
- “ibm,associativity” property associated
- with the traditional notion of a processor group which is sometimes packaged in
- a multi-chip module. A processor group has similar characteristics to an SMP,
- however, several processor groups get packaged densely within the same physical
- enclosure forming an SMP. While the intra processor group accesses are
- measurably greater than inter processor group accesses they are a second order
+
+
+ The second integer in the “ibm,associativity-reference-points”
+ property relates the 1 based ordinal in the associativity lists of the platform’s
+ “ibm,associativity” property associated
+ with the traditional notion of a processor group which is sometimes packaged in
+ a multi-chip module. A processor group has similar characteristics to an SMP,
+ however, several processor groups get packaged densely within the same physical
+ enclosure forming an SMP. While the intra processor group accesses are
+ measurably greater than inter processor group accesses they are a second order
effect. Subsequent ibm,associativity-reference-points entries are reserved.
-
+
Form 1When the “ibm,architecture-vec-5”
- property byte 5 bit 0 has the value of one, the
- “ibm,associativity-reference-points” property
- indicates boundaries between associativity domains presented by the
- “ibm,associativity” property containing
- “near” and “far” resources. The first such boundary
- in the list represents the 1 based ordinal in the associativity lists of the
- most significant boundary, with subsequent entries indicating progressively
+ property byte 5 bit 0 has the value of one, the
+ “ibm,associativity-reference-points” property
+ indicates boundaries between associativity domains presented by the
+ “ibm,associativity” property containing
+ “near” and “far” resources. The first such boundary
+ in the list represents the 1 based ordinal in the associativity lists of the
+ most significant boundary, with subsequent entries indicating progressively
less significant boundaries.
- Note: Platforms are encouraged to report
- boundaries of actual significance. Thus if a platform has only a single
- significant boundary to report, the preferred form of the
- “ibm,associativ¬ity-reference-points” would
- contain a single entry. However, providing two or more entries that reference
- the same associativity domains provides equivalent information and is a legal
+ Note: Platforms are encouraged to report
+ boundaries of actual significance. Thus if a platform has only a single
+ significant boundary to report, the preferred form of the
+ “ibm,associativ¬ity-reference-points” would
+ contain a single entry. However, providing two or more entries that reference
+ the same associativity domains provides equivalent information and is a legal
representation.
-
+
Dynamic Reconfiguration with Cross CEC I/O Drawers
- Should the configuration change in such a way that the associativity
- between an OS image’s resources changes, the platform notifies the OS
+ Should the configuration change in such a way that the associativity
+ between an OS image’s resources changes, the platform notifies the OS
via an event scan log. See .
- R1-R1--1.
- For the NUMA or Associativity
- Information option: If the platform configuration changes in such a
- way that the associativity between an OS image’s resources might have
- changed, the platform must notify the OS via an event scan or check exception
+ For the NUMA or Associativity
+ Information option: If the platform configuration changes in such a
+ way that the associativity between an OS image’s resources might have
+ changed, the platform must notify the OS via an event scan or check exception
log.
@@ -299,124 +299,130 @@ xml:lang="en">
- Maximum Associativity Domains
- Since the number of associativity domains that a platform may exhibit
- is not apparent from the associativity properties presented at boot time, the
- platform provides the “ibm,max-associativity-domains”
- property in the /rtas node of the device tree (see
+ Maximum and Current Associativity Domains
+ Since the number of associativity domains that a platform may exhibit
+ is not apparent from the associativity properties presented at boot time, the
+ platform provides the
+ “ibm,max-associativity-domains”
+ and the
+ “ibm,current-associativity-domains”
+ properties in the /rtas node of the device tree (see
).
- R1-R1--1.
- For the NUMA or Associativity
- Information option: The platform must provide the
- “ibm,max-associativity-domains” property in
+ For the NUMA or Associativity
+ Information option: The platform must provide the
+ “ibm,max-associativity-domains”
+ and the
+ “ibm,current-associativity-domains”
+ properties in
the /rtas node of the device tree.
-
+
Platform Resource Reassignment Notification Option (PRRN)
- LoPAR platforms that implement the LPAR option are allowed to
- transparently reassign the platform resources that are used by a partition. For
- instance, if a processor or memory unit is predicted to fail, the platform may
- transparently move the processing to an equivalent unused processor or the
- memory state to an equivalent unused memory unit. However, reassigning
- resources across NUMA boundaries may alter the performance of the partition.
- When such reassignment is necessary, the PRRN option provides mechanisms that
- inform the supporting OS of changes to the affinity among its platform
- resources. It is expected that handling such notifications will involve
- significant OS processing, therefore, changing affinity should be avoided, and
- when it is necessary to change the affinity of several of the resources owned
- by a partition, a single notification after all such changes have occurred is
+ LoPAR platforms that implement the LPAR option are allowed to
+ transparently reassign the platform resources that are used by a partition. For
+ instance, if a processor or memory unit is predicted to fail, the platform may
+ transparently move the processing to an equivalent unused processor or the
+ memory state to an equivalent unused memory unit. However, reassigning
+ resources across NUMA boundaries may alter the performance of the partition.
+ When such reassignment is necessary, the PRRN option provides mechanisms that
+ inform the supporting OS of changes to the affinity among its platform
+ resources. It is expected that handling such notifications will involve
+ significant OS processing, therefore, changing affinity should be avoided, and
+ when it is necessary to change the affinity of several of the resources owned
+ by a partition, a single notification after all such changes have occurred is
preferred.
- The OS and platform firmware negotiate their mutual support of the
- PRRN option via the ibm,client-architecture-support
- interface (See ). Should a partition be
- migrated from a platform that did not support the PRRN option, the target
- platform does not notify the partition’s OS of any PRRN events and, when
- possible avoids changing the affinity among the partition’s resources.
- Partitions that are about to be migrated complete/abort any in-process affinity
- change processing prior to the migration, and if the target platform does not
- support the PRRN option the partition will simply see no more PRRN
+ The OS and platform firmware negotiate their mutual support of the
+ PRRN option via the ibm,client-architecture-support
+ interface (See ). Should a partition be
+ migrated from a platform that did not support the PRRN option, the target
+ platform does not notify the partition’s OS of any PRRN events and, when
+ possible avoids changing the affinity among the partition’s resources.
+ Partitions that are about to be migrated complete/abort any in-process affinity
+ change processing prior to the migration, and if the target platform does not
+ support the PRRN option the partition will simply see no more PRRN
events.
- A PRRN event is signaled via the RTAS event-scan
- mechanism, which returns a Hot Plug Event message “fixed
- part” (See ) indicating “Platform
- Resource Reassignment”. In response to the Hot Plug Event message, the
- OS may call ibm,update-nodes to determine which resources
- were reassigned, and then ibm,update-properties to obtain
+ A PRRN event is signaled via the RTAS event-scan
+ mechanism, which returns a Hot Plug Event message “fixed
+ part” (See ) indicating “Platform
+ Resource Reassignment”. In response to the Hot Plug Event message, the
+ OS may call ibm,update-nodes to determine which resources
+ were reassigned, and then ibm,update-properties to obtain
the new affinity information about those resources.
- The PRRN event-scan RTAS message contains only
- the “fixed part” with the “Type” field set to the
- value 160 and no Extended Event Log. The four (4) byte Extended Event Log
- Length field is repurposed, since no Extended Event Log message is included, to
- pass the “scope” parameter that causes the
- ibm,update-nodes to return the nodes affected by the specific
+ The PRRN event-scan RTAS message contains only
+ the “fixed part” with the “Type” field set to the
+ value 160 and no Extended Event Log. The four (4) byte Extended Event Log
+ Length field is repurposed, since no Extended Event Log message is included, to
+ pass the “scope” parameter that causes the
+ ibm,update-nodes to return the nodes affected by the specific
resource reassignment.Requirements:
- R1-R1--1.
- For the PRRN Option:
- The platform must support the negotiation of the Associativity Information
- Option Control Platform Resource Reassignment Notification (Affinity Change)
- flag via the ibm,client-architecture-support
+ For the PRRN Option:
+ The platform must support the negotiation of the Associativity Information
+ Option Control Platform Resource Reassignment Notification (Affinity Change)
+ flag via the ibm,client-architecture-support
interface.
-
+
- R1-R1--2.
- For the PRRN Option:
- If the client code did not claim support for the PRRN option via the
- ibm,client-architecture-support interface the platform must not
- present PRRN events per section For the PRRN Option:
+ If the client code did not claim support for the PRRN option via the
+ ibm,client-architecture-support interface the platform must not
+ present PRRN events per section .
-
+
- R1-R1--3.
- For the combination of the PRRN
- and Partition Suspension Options: To avoid firmware function
- conflicts the client code must complete or abort any PRRN processing prior to
+ For the combination of the PRRN
+ and Partition Suspension Options: To avoid firmware function
+ conflicts the client code must complete or abort any PRRN processing prior to
exercising the Partition Suspension option.
-
+
- R1-R1--4.
- For the PRRN Option:
- The platform must inform the client code of platform resource reassignments via
- the event-scan RTAS mechanism with a “fixed
- part” only event return message as presented in For the PRRN Option:
+ The platform must inform the client code of platform resource reassignments via
+ the event-scan RTAS mechanism with a “fixed
+ part” only event return message as presented in
-
+
- R1-R1--5.
- For the PRRN Option:
- The platform must support the Platform Resource Reassignment scope (negative of
- the value contained in bits 32:64 of the RTAS Event Return Format (Fixed Part)
- for PRRN events) input parameter to input the
+ For the PRRN Option:
+ The platform must support the Platform Resource Reassignment scope (negative of
+ the value contained in bits 32:64 of the RTAS Event Return Format (Fixed Part)
+ for PRRN events) input parameter to input the
ibm,update-nodes RTAS call.
@@ -513,7 +519,7 @@ xml:lang="en">
The scope parameter to be input the ibm,update-nodes RTAS call
- to retrieve the nodes that were changed by selected “Hot Plug”
+ to retrieve the nodes that were changed by selected “Hot Plug”
events.
diff --git a/RTAS/sec_rtas_get_indices.xml b/RTAS/sec_rtas_get_indices.xml
index d72f2b4..56b5b34 100644
--- a/RTAS/sec_rtas_get_indices.xml
+++ b/RTAS/sec_rtas_get_indices.xml
@@ -1,7 +1,7 @@
-
+
ibm,get-indices Call
-
- The RTAS function
+
+ The RTAS function
ibm,get-indices is used to obtain the indices and
location codes for a specified indicator or sensor token. It allows for
obtaining the list of indicators and sensors dynamically and therefore
assists in any Dynamic Reconfiguration operation that involves indicators
- and sensors being added or deleted from the platform (unlike the
- /rtas node
- “<vendor>,indicator-<token>”,
- “<vendor>,sensor-<token>”,
+ and sensors being added or deleted from the platform (unlike the
+ /rtas node
+ “<vendor>,indicator-<token>”,
+ “<vendor>,sensor-<token>”,
and “ibm,environmental-sensor” properties).
This call also allows discontiguous indices for a particular indicator or
- sensor type (unlike the
- “rtas-indicators”,
- “rtas-sensors”, and
+ sensor type (unlike the
+ “rtas-indicators”,
+ “rtas-sensors”, and
“ibm,environmental-sensor” properties).This RTAS call is not used for DR indicators (9001, 9002, and 9003)
or DR sensors (9003). See the following sections in the DR chapter for more
- information:
- and
+ information:
+ and
.
- It may require several calls to the
+ It may require several calls to the
ibm,get-indices RTAS routine to get the entire list of
indicators or sensors of a particular type. Each call may specify a
different work area.
- The OS may not interleave calls to
+ The OS may not interleave calls to
ibm,get-indices for different indicator or sensor
types. Other standard RTAS locking rules apply.
- R1-R1--1.
- For all DR options: The RTAS function
+ For all DR options: The RTAS function
ibm,get-indices must implement the argument call buffer
- defined by
+ defined by
.
-
+
- When the 990x
+ When the 990x
Status is returned, it is suggested that software delay
for 10 raised to the x milliseconds (where x is the last digit of the 990x
- return code), before calling
+ return code), before calling
ibm,get-indices with the same Starting Number and
- Indicator Type. However, software may issue the
+ Indicator Type. However, software may issue the
ibm,get-indices call again either earlier or later than
this.
-
+
- R1-R1--2.
- The OS must not interleave calls to
+ The OS must not interleave calls to
ibm,get-indices for different indicator or sensor
types.
-
+
- R1-R1--3.
- On the first call to get a particular
+ On the first call to get a particular
Indicator Type, the caller must provide a Starting
Number of 1 (32-bit integer)
-
+
- R1-R1--4.
- When
+ When
ibm,get-indices is called with a Starting Number of 1,
firmware must refresh any stale data in previously cached firmware buffers
for that indicator (for example, data made stale by a Dynamic
Reconfiguration operation).
-
+
- R1-R1--5.
- When calling
+ When calling
ibm,get-indices with a Starting Number of 1, a
- previously returned
+ previously returned
Next Starting Number value must be discarded.
-
+
- R1-R1--6.Optionally, if firmware detects a change in
- the indicator list before the entire list is returned, the
+ the indicator list before the entire list is returned, the
ibm,get-indices call must return a -4 and the caller
must start again with a Starting Number of 1.
-
+
- R1-R1--7.The return data format in the work area for
all sensors and indicators must be as follows:
-
-
+
+ Number Returned: 32-bit integer representing the number of
indicator indices returned on this call
-
+
Sets of (32-bit integer index, 32-bit integer length of location
code including NULLs, location code string (NULL terminated and padded to
nearest 4 byte boundary)), one set per indicator or sensor, with the number
of sets indicated by the first integer in this work buffer
-
+
-
+
- R1-R1--8.
- If the
+ If the
Status returned is 1 (more data available, call again),
- then the caller must call
- ibm,get-indices again with the
+ then the caller must call
+ ibm,get-indices again with the
Starting Number parameter set to the Next Starting
Number integer from the previously returned buffer.
-
+
- R1-R1--9.
- The ibm,get-indices RTAS call must return the
+ The ibm,get-indices RTAS call must return the
Status value of -3 for the following conditions:
-
-
+
+ Indicator type not supported
-
+
No indicators of specified Indicator Type available to
caller
-
+
-
+
- R1-R1--10.
- If the ibm,get-indices RTAS call returns a
+ If the ibm,get-indices RTAS call returns a
Status of anything other than 0 or 1 is returned, the
caller must consider that the contents of the work area is not
defined.
-
+
- R1-R1--11.
- The work area specified in the
+ The work area specified in the
ibm,get-indices RTAS call argument buffer must be
contiguous in logical real memory and must reside below 4GB.
-
+
- R1-R1--12.The ibm,get-indices RTAS call must only return the
@@ -360,94 +360,94 @@
the time of the call.
-
+
- R1-R1--13.The ibm,get-indices RTAS call must make no assumptions
about the contents of the work area on the beginning of the call.
-
+
- R1-R1--14.
- When the platform supports the
+ When the platform supports the
ibm,get-indices RTAS call, the device tree must include
- the
+ the
“ibm,get-indicator-indices-types” property
- in the
+ in the
/rtas node if the call is to be used for getting
- indicator information and must include the
+ indicator information and must include the
“ibm,get-sensor-indices-types” property in
- the
+ the
/rtas node if the call is to be used for getting sensor
information.
-
+
- R1-R1--15.
- When an indicator token is provided in the
+ When an indicator token is provided in the
“ibm,get-indicator-indices-types” property,
- it must not be included in the
- “<vendor>,indicator-<token>”
- property and must not be included in the
+ it must not be included in the
+ “<vendor>,indicator-<token>”
+ property and must not be included in the
“rtas-indicators” property.
-
+
- R1-R1--16.
- When a sensor token is provided in the
+ When a sensor token is provided in the
“ibm,get-sensor-indices-types” property, it
- must not be included in the
- “<vendor>,sensor-<token>”
- property and must not be included in the
+ must not be included in the
+ “<vendor>,sensor-<token>”
+ property and must not be included in the
“rtas-sensors” property.
-
+
- R1-R1--17.When an environmental sensor token is
- provided in the
+ provided in the
“ibm,get-sensor-indices-types” property,
- users of data in the
+ users of data in the
“ibm,environmental-sensors” property for
that sensor token must not assume that the indices are contiguous for that
sensor token (that is, any of the indices between 0 and the maxindex,
inclusive, may be missing).
-
+
- R1-R1--18.When the value of
- any index returned is 0xFFFFFFFF, the OS must use the
- ibm,get-dynamic-sensor-state and
+ any index returned is 0xFFFFFFFF, the OS must use the
+ ibm,get-dynamic-sensor-state and
ibm,set-dynamic-indicator RTAS functions for this
sensor or indicator, using the location code to identify the sensor or
indicator.
-
+
- R1-R1--19.
- The OS must not call
- get-sensor-state or
+ The OS must not call
+ get-sensor-state or
get-indicator with an index value of 0xFFFFFFFF.
@@ -455,35 +455,35 @@
ibm,set-dynamic-indicator RTAS Call
-
- This RTAS call behaves as the RTAS
+
+ This RTAS call behaves as the RTAS
set-indicator call, except that the instance of the
indicator is identified by a location code instead of a index.
- R1-R1--1.Platforms that
implement any indicators that are identified by location code instead of
- index (see Requirement
- ) must implement the
+ index (see Requirement
+ ) must implement the
ibm,set-dynamic-indicator RTAS function.
-
+
- R1-R1--2.
- The RTAS function
+ The RTAS function
ibm,set-dynamic-indicator must implement the argument
- call buffer defined by
+ call buffer defined by
.
-
+
- Argument Call Buffer
+ Argument Call Buffer
ibm,set-dynamic-indicator
@@ -521,7 +521,7 @@
- Token for
+ Token for
ibm,set-dynamic-indicator
@@ -564,7 +564,7 @@
- Desired new state; see
+ Desired new state; see
.
@@ -576,7 +576,7 @@
Real or Logical address of a location code string, in the
- format defined by Requirement
+ format defined by Requirement
@@ -601,141 +601,141 @@
- When 990x
+ When 990x
Status is returned, it is suggested that software
- delay for 10 raised to the power
- x milliseconds (where
+ delay for 10 raised to the power
+ x milliseconds (where
x is the last digit of the 990x return code), before
- calling
+ calling
ibm,set-dynamic-indicator with the same indicator
- type and location code. However, software may call
+ type and location code. However, software may call
ibm,set-dynamic-indicator again either earlier or
later than this.
-
+
- R1-R1--3.
- The OS must not call
+ The OS must not call
ibm,set-dynamic-indicator with a different indicator
- until a non-busy return
- Status has been received from the previous
+ until a non-busy return
+ Status has been received from the previous
ibm,set-dynamic-indicator call.
-
+
- R1-R1--4.
- The location code string referenced by the
- Location Code Address argument in the
+ The location code string referenced by the
+ Location Code Address argument in the
ibm,set-dynamic-indicator argument call buffer must
reside in contiguous in real memory below an address of 4GB.
-
+
- R1-R1--5.The input data
format in the work area must be as follows:
-
-
+
+ 32-bit integer length of the location code string, including
NULL
-
+
Location code string, NULL terminated, identifying the sensor to
be set.
-
+
-
+
- R1-R1--6.The platform must not modify the location
code string.
-
+
- R1-R1--7.The OS must only use this call for
- indicators which have been provided by the
+ indicators which have been provided by the
ibm,get-indices RTAS call with an index value of
0xFFFFFFFF.
-
+
- R1-R1--8.Platforms must identify all indicators
except types 9006 and 9007 by index.
-
+
- R1-R1--9.
- The ibm,set-dynamic-indicator RTAS call must return A
+ The ibm,set-dynamic-indicator RTAS call must return A
Status of -3 for the following conditions:
-
-
+
+ Indicator type not supported
-
+
The specified location code does not identify a valid
indicator
-
+
-
+
-
+
ibm,get-dynamic-sensor-state RTAS Call
- This RTAS call behaves as the RTAS
+ This RTAS call behaves as the RTAS
get-sensor-state call, except that the instance of
the sensor is identified by a location code instead of a index.
- R1-R1--1.Platforms that
implement any sensors that are identified by location code instead of
- index (see Requirement
- ) must implement the
+ index (see Requirement
+ ) must implement the
ibm,get-dynamic-sensor-state RTAS function.
-
+
- R1-R1--2.
- The RTAS function
+ The RTAS function
ibm,get-dynamic-sensor-state must implement the
- argument call buffer defined by
+ argument call buffer defined by
.
@@ -775,7 +775,7 @@
- Token for
+ Token for
ibm,get-dynamic-sensor-state
@@ -829,7 +829,7 @@
Real or Logical address of a location code string, in the
- format defined by Requirement
+ format defined by Requirement
@@ -861,122 +861,122 @@
- Current state of the sensor as defined in the
- Defined Values column of
+ Current state of the sensor as defined in the
+ Defined Values column of
.
- When 990x
+ When 990x
Status is returned, it is suggested that software
- delay for 10 raised to the power
- x milliseconds (where
+ delay for 10 raised to the power
+ x milliseconds (where
x is the last digit of the 990x return code), before
- calling
+ calling
ibm,get-dynamic-sensor-state with the same indicator
- type and location code. However, software may call
+ type and location code. However, software may call
ibm,get-dynamic-sensor-state again either earlier or
later than this.
-
+
- R1-R1--3.
- The OS must not call
+ The OS must not call
ibm,get-dynamic-sensor-state with a different sensor
- until a non-busy return
- Status has been received from the previous
+ until a non-busy return
+ Status has been received from the previous
ibm,get-dynamic-sensor-state call.
-
+
- R1-R1--4.The work area must be contiguous in real
memory and must reside below 4GB.
-
+
- R1-R1--5.The input data
format in the work area must be as follows:
-
-
+
+ 32-bit integer length of the location code string, including
NULL
-
+
Location code string, NULL terminated, identifying the sensor to
be set.
-
+
-
+
- R1-R1--6.The platform must not modify the location
code string.
-
+
- R1-R1--7.The OS must only use this call with sensors
- which have been provided by the
+ which have been provided by the
ibm,get-indices RTAS call with an index value of
0xFFFFFFFF.
-
+
- R1-R1--8.
- The platform must use the
+ The platform must use the
ibm,get-dynamic-sensor-state RTAS call only for
dynamic sensor types of 9004, 9006 and 9007.
-
+
- R1-R1--9.A Status of -3 must be returned for the following
conditions:
-
-
+
+ Sensor type not supported
-
+
The specified location code does not identify a valid
sensor
-
+
-
+
-
+
ibm,get-vpd RTAS CallThis RTAS call allows for collection of VPD that changes after OS
@@ -985,33 +985,33 @@
device tree and what is reported with this RTAS call. Also, when this
RTAS call is implemented, all VPD, except PCI and I/O device VPD, which
is dynamically changed during OS run time is reported with this call and
- not via the
+ not via the
“ibm,vpd” property in the OF device
tree.
- R1-R1--1.For all Dynamic Reconfiguration options
except PCI Hot Plug, when the platform VPD can change dynamically due to
- a Dynamic Reconfiguration operation, the platform must implement the
+ a Dynamic Reconfiguration operation, the platform must implement the
ibm,get-vpd RTAS call.
-
+
- R1-R1--2.
- The RTAS function
+ The RTAS function
ibm,get-vpd must implement the argument call buffer
- defined by
+ defined by
.
-
+
- Argument Call Buffer
+ Argument Call Buffer
ibm,get-vpd
@@ -1047,7 +1047,7 @@
- Token for
+ Token for
ibm,get-vpd
@@ -1114,7 +1114,7 @@
Integer representing the sequence number of the call.
First call in sequence starts with 1, following calls (if
- necessary) use the
+ necessary) use the
Next Sequence Number returned from the
previous call.
@@ -1145,7 +1145,7 @@
- Return this integer as the
+ Return this integer as the
Sequence Number parameter on the next call
to continue the sequence, or 1 if no more calls are
required
@@ -1165,178 +1165,178 @@
- When the 990x
+ When the 990x
Status is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
- the 990x return code), before calling
+ the 990x return code), before calling
ibm,get-vpd with the same input parameters. However,
- software may issue the
+ software may issue the
ibm,get-vpd call again either earlier or later than
this.
-
+
- R1-R1--3.
- On the first call to
+ On the first call to
ibm,get-vpd for a particular VPD gathering operation,
- the caller must provide a
+ the caller must provide a
Sequence Number of 1 (32-bit integer)
-
+
- R1-R1--4.
- Upon calling
- ibm,get-vpd with a
- Sequence Number of 1, a previously returned
+ Upon calling
+ ibm,get-vpd with a
+ Sequence Number of 1, a previously returned
Next Sequence Number must be discarded. This means
- that multiple calls to
+ that multiple calls to
ibm,get-vpd cannot be interleaved by multiple
- processors, and if processor “B” starts a new
+ processors, and if processor “B” starts a new
ibm,get-vpd sequence while processor “A”
has a call sequence in process (that is, the function on processor
- “A” has returned a
+ “A” has returned a
Status of 1, and the subsequent call has not yet been
made) then the call sequence on processor “A” is
abandoned.
-
+
- R1-R1--5.Optionally, if firmware detects a change in
- the VPD being requested before the entire VPD is returned, the
- ibm,get-vpd call must return a
+ the VPD being requested before the entire VPD is returned, the
+ ibm,get-vpd call must return a
Status of -4 and the caller must start again with a
Starting Number of 1.Implementation Note: The platform should not impede
- forward progress by continuously returning a
+ forward progress by continuously returning a
Status of -4.
-
+
- R1-R1--6.The return data format in the work area
must be such that after returning all the data and concatenating all data
together in the order received, that the data is the same as is obtained
- from the
+ from the
“ibm,vpd” property of the OF device
tree.
-
+
- R1-R1--7.Each stanza of the returned data must
include the YL (location code) keyword.
-
+
- R1-R1--8.
- If the
+ If the
ibm,get-vpd RTAS call is implemented, then the
- platform must not provide the
- “ibm,vpd” or
+ platform must not provide the
+ “ibm,vpd” or
“ibm,loc-code” properties in the OF
- device tree
+ device tree
root node.
-
+
- R1-R1--9.
- If the
+ If the
ibm,get-vpd RTAS call is implemented, then any VPD
- which may change after OS boot must be reported via the
+ which may change after OS boot must be reported via the
ibm,get-vpd RTAS call.
-
+
- R1-R1--10.
- If the
+ If the
Status returned is 1 (more data available, call
- again), then the caller must call
- ibm,get-vpd again with the
- Sequence Number parameter set to the
+ again), then the caller must call
+ ibm,get-vpd again with the
+ Sequence Number parameter set to the
Next Sequence Number integer from the previously
returned call.
-
+
- R1-R1--11.
- If a
+ If a
Status of anything other than 0 or 1 is returned, the
contents of the work area is not defined.
-
+
- R1-R1--12.The work area must be contiguous in real
memory and must reside below 4GB.
-
+
- R1-R1--13.Firmware cannot count on the contents of
- the work area at the beginning of any call to
- ibm,get-vpd (regardless of the value of the
+ the work area at the beginning of any call to
+ ibm,get-vpd (regardless of the value of the
Sequence Number).
-
+
- R1-R1--14.
- The location code referenced by the
+ The location code referenced by the
Pointer to Location Code parameter must reside in
contiguous real memory below an address of 4GB.
-
+
- R1-R1--15.
- If the
+ If the
ibm,get-vpd RTAS call is implemented, then firmware
- must supply the
- “ibm,vpd-size” property in the
+ must supply the
+ “ibm,vpd-size” property in the
/rtas node, the value of which is a single cell,
- encoded as with
+ encoded as with
encode-int, which is the estimated maximum size in
- bytes of the VPD that is returned if the
- Pointer to Location Code parameter to the
+ bytes of the VPD that is returned if the
+ Pointer to Location Code parameter to the
ibm,get-vpd RTAS function is NULL (that is, all
system VPD). This size should take in to account possible concurrent
addition of new platform elements after the partition is started. If
@@ -1345,44 +1345,44 @@
Software Implementation Notes:
-
-
+
+ An OS should be prepared for older versions of firmware where
- the
+ the
“ibm,vpd-size” property is not
provided.
-
+
Each stanza of the returned data must include the YL (location
code) keyword.
-
+
-
+
-
+
Managing Storage Preservation
-
+
Platforms may optionally preserve selected regions of storage
- (LMBs) across client program boot cycles.
+ (LMBs) across client program boot cycles.
for more information.
- R1-R1--1.For the Storage Preservation option: The platform
- must implement the
+ must implement the
ibm,manage-storage-preservation RTAS argument call
- buffer as defined by
+ buffer as defined by
.
-
+
ibm,manage-storage-preservation Argument Call
Buffer
@@ -1420,7 +1420,7 @@
- Token for
+ Token for
ibm,manage-storage-preservation
@@ -1467,7 +1467,7 @@
- The high order 32 bits of the LMB's
+ The high order 32 bits of the LMB's
“reg” property (Subfunctions
1-3)
@@ -1479,7 +1479,7 @@
- The low order 32 bits of the LMB's
+ The low order 32 bits of the LMB's
“reg” property (Subfunctions
1-3)
@@ -1509,7 +1509,7 @@
- If
+ If
Status= Success, the current preservation
state of specified LMB (Subfunctions 1-3)
@@ -1519,22 +1519,22 @@
-
+
- R1-R1--2.For the Storage Preservation option: The platform
- must include the
- “ibm,preservable” property in the
+ must include the
+ “ibm,preservable” property in the
/memory nodes of its OF device tree, containing a
value which reflects the platform's ability to preserve the specific
LMB.
-
+
- R1-R1--3.For the Storage Preservation option: The value of the
@@ -1542,45 +1542,45 @@
LMB must be 0 (cannot be preserved).
-
+
- R1-R1--4.For the Storage Preservation option: The platform
- must not preserve the first LMB, thus must indicate a value of 0 for the
+ must not preserve the first LMB, thus must indicate a value of 0 for the
“ibm,preservable” property for the first
LMB.
-
+
- R1-R1--5.For the Storage Preservation option: The platform
- must include the
- “ibm,preserved” property in the
+ must include the
+ “ibm,preserved” property in the
/memory nodes of its OF device tree, valued to
reflect the platform's preservation state of the specific LMB.
-
+
- R1-R1--6.For the Storage Preservation option: The platform, on
- a reboot, must include in the OF
- /rtas node the
+ a reboot, must include in the OF
+ /rtas node the
“ibm,preserved-storage” property if the
previous client program registered one or more of its LMBs for
preservation.
-
+
- R1-R1--7.For the Storage Preservation option: If the client
@@ -1588,14 +1588,14 @@
the LMB's storage state across client program reboots.
-
+
- R1-R1--8.For the Storage Preservation option: The platform, on
- a reboot, must include in the OF
- /rtas node the
+ a reboot, must include in the OF
+ /rtas node the
“ibm,request-partition-shutdown” property
which reflects the value of the partition shutdown configuration
variable, and if this property is not present, a value of 0 must be
@@ -1605,10 +1605,10 @@
-
+
ibm,lpar-perftools RTAS Call
-
+
This RTAS call provides access to platform-level facilities for
performance tools running in a partition on an LPAR system. Platforms may
require platform-specific tools, beyond the scope of this architecture,
@@ -1616,26 +1616,26 @@
- R1-R1--1.For the Performance Tool Support option: The platform
must implement the LPAR option.
-
+
- R1-R1--2.For the Performance Tool Support option: RTAS must
- implement the
+ implement the
ibm,lpar-perftools call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
- Argument Call Buffer
+ Argument Call Buffer
ibm,lpar-perftools
@@ -1671,7 +1671,7 @@
- Token for
+ Token for
ibm,lpar-perftools
@@ -1746,7 +1746,7 @@
Integer representing the sequence number of this call.
First call in sequence starts with 1, following calls (if
- necessary) use the
+ necessary) use the
Next Sequence Number returned from the
previous call.
@@ -1779,7 +1779,7 @@
- Return this integer as the
+ Return this integer as the
Sequence Number parameter on the next call,
or 1 if no more calls are required.
@@ -1787,22 +1787,22 @@
- When 990x
+ When 990x
Status is returned, it is suggested that software
delay for 10 raised to the x milliseconds (where x is the last digit of
- the 990x return code), before calling the
+ the 990x return code), before calling the
ibm,lpar-perftools call with the same input
- parameters. However, software may issue the
+ parameters. However, software may issue the
ibm,lpar-perftools call again earlier or later than
this.
-
+
- R1-R1--3.
- For the Performance Tool Support option: For
+ For the Performance Tool Support option: For
subfunction value 1, on input the first 8 bytes of
the work area must contain the hypervisor IAR address to be converted. On
output, the first 8 bytes of the work area contain the offset of this
@@ -1814,28 +1814,28 @@
address was not valid.
-
+
- R1-R1--4.For the Performance Tool support option: The work
area must reside in contiguous memory.
-
+
- R1-R1--5.
- For the Performance Tool Support option: If a
+ For the Performance Tool Support option: If a
Status of anything other than 0 is returned, the
contents of the work area are not defined.
-
+
- R1-R1--6.For the Performance Tool Support option: A partition
@@ -1843,7 +1843,7 @@
This means that if one processor in the partition initiates this call,
receives a Busy or Extended Delay return, and then another processor
calls this function with a sequence number of 1, a subsequent call using
- the
+ the
Next Sequence Number returned to the first processor
results in a Parameter Error return code.
@@ -1851,66 +1851,66 @@
-
+
ibm,suspend-me RTAS Call
- The
+ The
ibm,suspend-me RTAS call provides the calling OS the
ability to suspend processing. Suspension of processing is required as
part of OS hibernation or migration to another platform. This RTAS call
is made by the last active processor thread of a partition. The OS uses
- the H_JOIN hcall() (see
+ the H_JOIN hcall() (see
) to deactivate other
processing threads. Processing treads may exit H_JOIN due to an
- unmaskable interrupt; if a thread has exited H_JOIN,
+ unmaskable interrupt; if a thread has exited H_JOIN,
ibm,suspend-me fails with a status of “multiple
processor threads active”. The wake up from suspension is triggered
- by partition state change (see
+ by partition state change (see
sections on "Partition Migration"
- and "Partition Hibernation"). The
+ and "Partition Hibernation"). The
ibm,suspend-me RTAS call returns only on the calling
- virtual processor. Other virtual processors that were inactive when
+ virtual processor. Other virtual processors that were inactive when
ibm,suspend-me was called remain so until they are
proded by the OS.While the logical configuration of a suspended partition remains
- static, the physical properties may change; the OS may wish to issue
- ibm,update-nodes (see
+ static, the physical properties may change; the OS may wish to issue
+ ibm,update-nodes (see
) to determine if any device
tree nodes changed, and then refresh its view of the device
- tree physical properties using
- ibm,update-properties (see
- ) and/or
- ibm,configure-connector (see
+ tree physical properties using
+ ibm,update-properties (see
+ ) and/or
+ ibm,configure-connector (see
). Also during suspension, some
- system parameters may have changed. See
+ system parameters may have changed. See
, for details. The OS may want
to re-scan selected system parameters.
- R1-R1--1.For the Partition Suspension option: The platform
- must implement the Logical Partitioning option (see
+ must implement the Logical Partitioning option (see
)
.
-
+
- R1-R1--2.For the Partition Suspension option: RTAS must
- implement the
+ implement the
ibm,suspend-me call within a logical partition using
- the argument call buffer defined by
+ the argument call buffer defined by
.
-
+
-
+
- R1-R1--3.
- For the Partition Suspension option: The
+ For the Partition Suspension option: The
ibm,suspend-me RTAS call must determine that the
calling partition is in the “suspendable state”, else return
a status of -9004 “Partition not suspendable”.
-
+
- R1-R1--4.
- For the Partition Suspension option: The
+ For the Partition Suspension option: The
ibm,suspend-me RTAS call must determine that the
calling partition has no other active processor thread, else return a
status of -9005 “Multiple processor threads active”.
-
+
- R1-R1--5.For the Partition Suspension option: The platform
- must implement the Thread Join option (see
+ must implement the Thread Join option (see
).
-
+
- R1-R1--6.For the Partition Suspension option: The platform
- must restore all partition state as of the time of the call to
- ibm,suspend-me prior to returning from the
+ must restore all partition state as of the time of the call to
+ ibm,suspend-me prior to returning from the
ibm,suspend-me RTAS call, except for the values of
those Open Firmware Device tree properties as reported using the Update
- OF Tree option, and the system parameters given in
+ OF Tree option, and the system parameters given in
.
-
+
- R1-R1--7.For the Partition Suspension option: The platform
must be prepared to respond to OS requests for updated device tree
- information immediately after returning from the
+ information immediately after returning from the
ibm,suspend-me RTAS call.
-
+
- R1-R1--8.For the Partition Suspension option: The platform
must support the “update OF tree” option.
-
+
- R1-R1--9.For the Partition Suspension option: The platform
must support the “Partner partition suspended” CRQ Transport
- Event (See
+ Event (See
).
-
+
- R1-R1--10.
- For the Partition Suspension option: The
+ For the Partition Suspension option: The
ibm,suspend-me RTAS call must cause the platform to
deliver “Partner partition suspended” CRQ Transport Events to
- both CRQs of all CRQ connections associated with the partition calling
+ both CRQs of all CRQ connections associated with the partition calling
ibm,suspend-me.
- Note: The transport events are visible to the partition calling
+ Note: The transport events are visible to the partition calling
ibm,suspend-me after the subsequent resume from
suspension, while the transport events are immediately visible to the
partner partitions of the caller at the time of the suspend.
-
+
- R1-R1--11.
- For the Partition Suspension option: The
+ For the Partition Suspension option: The
ibm,suspend-me RTAS call must cause the platform to
set the state of all of the caller’s CRQs to disabled.
-
+
- R1-R1--12.For the Partition Suspension option: The platform
must implement the H_ENABLE_CRQ hcall() using the syntax and semantics
- described in
+ described in
.
-
+
- R1-R1--13.For platforms that implement the Partition Suspension and VSCSI
- options: The
+ options: The
“compatible” property of the
- platform’s
- v-scsi and
- v-scsi-host nodes must include
- “IBM,v-scsi-2” and
+ platform’s
+ v-scsi and
+ v-scsi-host nodes must include
+ “IBM,v-scsi-2” and
“IBM,v-scsi-host-2” respectively
indicating the platform supports the “Partner partition
suspended” CRQ Transport Event.
-
+
- R1-R1--14.For the Partition Suspension option: If the OS is
participating in OS surveillance, to avoid a surveillance time out, the
- OS must disable surveillance (see
- ) prior to calling
+ OS must disable surveillance (see
+ ) prior to calling
ibm,suspend-me.
-
+
- R1-R1--15.For the Partition Suspension option: The platform
- must implement the LRDR option (See
+ must implement the LRDR option (See
).
-
+
- R1-R1--16.For the Partition Suspension option: The logical
- configuration of a partition, including its view of the
+ configuration of a partition, including its view of the
rtas-display-device, and rtas tone facility must not
change while a partition is suspended.
-
+
- R1-R1--17.For the Partition Suspension option: The platform
@@ -2174,21 +2174,21 @@
system parameter, it does not do so after suspension.
-
+
- R1-R1--18.For the Partition Suspension option: The platform
must limit the system parameters that change values during suspension to
- those specified in
+ those specified in
(all system parameters not
specified are preserved).
-
+
- R1-R1--19.For the Partition Suspension option: The platform
@@ -2196,17 +2196,17 @@
during the suspension. Other SLB entries are subject to loss.
-
+
- R1-R1--20.For the Partition Suspension option with the Platform
- Facilities Option: The
+ Facilities Option: The
ibm,suspend-me RTAS call must determine that the
calling partition has no outstanding coprocessor operations else return a
status of -9005 “Outstanding COP Operations”.
-
+
System Parameters that May Change During Partition
Migration and Hibernation
@@ -2502,10 +2502,10 @@
-
+
ibm,update-nodes RTAS Call
-
+
This RTAS call is used to determine which device tree nodes have
changed due to a massive platform reconfiguration such as when the
partition is migrated between machines. Differing platform
@@ -2515,7 +2515,7 @@
aligned area of storage below the first 4 GB; as such, it may not be
large enough to contain the reports of all changed nodes. The status
value of 1 is used to inform the caller that there are more updates to
- report and that it will have to call the
+ report and that it will have to call the
ibm,update-nodes RTAS again to receive them. On
subsequent calls the state variable, which is set to zero on the first
call, is set to the value returned on the previous call, to supply RTAS
@@ -2533,65 +2533,65 @@
for the terminator -- thus the terminator can be considered a special
encoding of a no-op operator.
-
+ The opcode of 0x01 is used for deleted nodes -- the operands are
- the
+ the
phandle values for the deleted nodes.
-
+
The opcode of 0x02 is used for updated nodes -- the operands are
- the
+ the
phandle values for the updated nodes. The updated
- properties are obtained using the
+ properties are obtained using the
ibm,update-properties RTAS call.
-
+
The opcode of 0x03 is used for adding nodes -- the operands are
- pairs of
- phandle and
- drc-index values; the
+ pairs of
+ phandle and
+ drc-index values; the
phandle value denotes the parent node of the node to
- be added and the
- ibm,drc-index value is passed with the
+ be added and the
+ ibm,drc-index value is passed with the
ibm,configure-connector RTAS call to obtain the
contents of the added node.
-
-
+
+
To make processing of device tree updates simpler, all opcode 0x01
(delete) operations (if any) are presented prior to all opcode 0x02
(update) operations (if any), and finally any 0x03 (addition) operations
- are presented. The
- phandle operand values are the same
- phandle values as reported by the
+ are presented. The
+ phandle operand values are the same
+ phandle values as reported by the
“ibm,phandle” property.
- R1-R1--1.For the Update OF Tree option: The platform must
- include the
+ include the
“ibm,phandle” property in all OF nodes
- specified in
+ specified in
.
-
+
- R1-R1--2.For the Update OF Tree option: The platform must
- implement the
+ implement the
ibm,update-nodes RTAS call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
Argument Call Buffer
ibm,update-nodes
@@ -2629,7 +2629,7 @@
- Token for
+ Token for
ibm,update-nodes
@@ -2670,7 +2670,7 @@
- Values per
+ Values per
.
@@ -2697,9 +2697,9 @@
-
+
- R1-R1--3.ibm,update-nodes RTAS call work area must be 4 KB
@@ -2707,18 +2707,18 @@
RTAS may return -3 “Parameter Error”.
-
+
- R1-R1--4.ibm,update-nodes RTAS for a given value of “
- Scope” must be formatted as specified in
+ Scope” must be formatted as specified in
, else RTAS may return -3
“Parameter Error”.
-
+
- Initial Format of Work Area for
+ Initial Format of Work Area for
ibm,update-nodes
@@ -2726,7 +2726,7 @@
0x00000000 (State Variable indicates Initial call for
- specified
+ specified
Scope)
@@ -2747,20 +2747,20 @@
-
+
- R1-R1--5.Upon successful return (non-negative status
- value) from
+ value) from
ibm,update-nodes the work area must by formatted as
- defined in
- . (Note each entry in
+ defined in
+ . (Note each entry in
is 4 bytes long.)
-
+
- Format of Work Area for
+ Format of Work Area for
ibm,update-nodes
@@ -2795,144 +2795,144 @@
-
+
- R1-R1--6.
- ibm,update-nodes RTAS call operation list for the
+ ibm,update-nodes RTAS call operation list for the
ibm,update-nodes RTAS call must contain an operator
(4 bytes naturally aligned) and zero or more 4 byte operands up to the
end of the work area.
-
+
- R1-R1--7.
- An operator in an
+ An operator in an
ibm,update-nodes RTAS call operation list must be
formatted with, starting at the high order byte, a single byte opcode
followed by 3 bytes encoded with the binary value of the number of
operands that follow.
-
+
- R1-R1--8.
- An operator in an
+ An operator in an
ibm,update-nodes RTAS call operation list with an
operand length field of zero must be considered to perform no
operation.
-
+
- R1-R1--9.
- The opcode of 0x01 in an
+ The opcode of 0x01 in an
ibm,update-nodes RTAS call operation list must be
used to denote node deletions.
-
+
- R1-R1--10.
- The operands for opcode 0x01 in an
+ The operands for opcode 0x01 in an
ibm,update-nodes RTAS call operation list must be the
-
+
phandle values for the deleted nodes.
-
+
- R1-R1--11.
- The opcode of 0x02 in an
+ The opcode of 0x02 in an
ibm,update-nodes RTAS call operation list must be
used to denote updated nodes.
-
+
- R1-R1--12.
- The operands for opcode 0x02 in an
+ The operands for opcode 0x02 in an
ibm,update-nodes RTAS call operation list must be the
phandle values for the updated nodes that may be used
- as the
+ as the
ibm,update-properties RTAS call argument to obtain
the changed properties of the updated node.
-
+
- R1-R1--13.
- The opcode of 0x03 in an
+ The opcode of 0x03 in an
ibm,update-nodes RTAS call operation list must used
for the added nodes.
-
+
- R1-R1--14.
- The operands for opcode of 0x03 in an
- ibm,update-nodes RTAS call operation list must be
- phandle and
+ The operands for opcode of 0x03 in an
+ ibm,update-nodes RTAS call operation list must be
+ phandle and
drc-index value pairs (each value being 4 bytes
on a natural boundary totalling 8 bytes for the pair) denoting the parent
- node of the added node and the
+ node of the added node and the
ibm,configure-connector RTAS call argument to obtain
the contents of the added node respectively.
-
+
- R1-R1--15.
- All opcode 0x01 (delete) in an
+ All opcode 0x01 (delete) in an
ibm,update-nodes RTAS call operation list (if any)
must be presented prior to any opcode 0x02 (update) operations (if
any).
-
+
- R1-R1--16.
- All opcode 0x02 (update) in an
+ All opcode 0x02 (update) in an
ibm,update-nodes RTAS call operation list (if any)
must be presented prior to any opcode 0x03 (add) operations (if
any).
-
+
- R1-R1--17.
- The work area on subsequent call(s) to
- ibm,update-nodes RTAS for the same value of the
- “Scope” must be formatted as specified in
+ The work area on subsequent call(s) to
+ ibm,update-nodes RTAS for the same value of the
+ “Scope” must be formatted as specified in
, else RTAS may return -3
“Parameter Error”.
-
+
- Format of Work Area for Subsequent Calls to
+ Format of Work Area for Subsequent Calls to
ibm,update-nodes
@@ -2940,7 +2940,7 @@
Value of the 1st 16 bytes of the returned work area from
- last call to
+ last call to
ibm,update-nodes RTAS that returned status
of 1.
@@ -2957,31 +2957,31 @@
-
+
- R1-R1--18.
- The “Scope” argument for the
+ The “Scope” argument for the
ibm,update-nodes RTAS call must be one of the values
- specified in the scope value column of
+ specified in the scope value column of
, else RTAS may return -3
“Parameter Error”.
-
+
- R1-R1--19.
- For the
+ For the
ibm,update-nodes RTAS call, the platform must
- restrict its reported node updates to those specified in
- for the value of the specified
+ restrict its reported node updates to those specified in
+ for the value of the specified
“Scope” argument.
-
+
- Nodes That May be Reported by
+ Nodes That May be Reported by
ibm,update-nodes for a Given Value of the “
Scope” Argument
@@ -2994,8 +2994,8 @@
Scope Value
- Reportable node types (value of
- “name” or
+ Reportable node types (value of
+ “name” or
“device_type” property)
@@ -3007,7 +3007,7 @@
Negative values: Platform Resource Reassignment events as
- from
+ from
event-scan RTAS
@@ -3243,20 +3243,20 @@
-
+
ibm,update-properties RTAS Call
-
+
This RTAS call is used to report updates to the properties changed
due to a massive platform reconfiguration such as when the partition is
migrated between machines. This RTAS call reports changes in the node
specified by the phandle value in the work area passed using the Work
Area Address argument. The phandle value may be that of a critical node
- that the caller is interested in or one reported by
+ that the caller is interested in or one reported by
ibm,update-nodes RTAS call. These changes may include
any combination of new values, deleted and added properties. Updates for
a given node are retained until the platform is subsequently
- reconfigured, and remain available to subsequent calls to
+ reconfigured, and remain available to subsequent calls to
ibm,update-nodes.There may be more changes than can be reported in a single 4 K work
area. In this case, the RTAS call returns with a status of 1 “More
@@ -3265,13 +3265,13 @@
is to start with the first changed property for the specified updated
node. On a call with a status value of 1, the first sixteen (16) bytes of
the work area contain values that, when subsequently supplied in the work
- area of another call to
+ area of another call to
ibm,update-properties RTAS, specify that the call
returns the updated property data for properties after those reported in
the previous call.A single updated property value string may exceed the capacity of a
single 4 K work area. In that case, the updated property value descriptor
- for the property appears in the work area of multiple sequential calls to
+ for the property appears in the work area of multiple sequential calls to
ibm,update-properties RTAS. When the updated property
value descriptor contains the final data for the property value, the
property string length field of the updated property value descriptor is
@@ -3283,21 +3283,21 @@
concatenated until the final updated property value descriptor is
processed.The first value returned, with an updated property name string of
- NULL, is always the node’s name (for example: full path ||
+ NULL, is always the node’s name (for example: full path ||
name property value || @ unit address) even if there
has been no change.
- R1-R1--1.For the Update OF Tree option: The platform must
- implement the
+ implement the
ibm,update-properties RTAS call using the argument
- call buffer defined by
+ call buffer defined by
.
-
+
Argument Call Buffer
ibm,update-properties
@@ -3335,7 +3335,7 @@
- Token for
+ Token for
ibm,update-properties
@@ -3376,7 +3376,7 @@
- Values per
+ Values per
.
@@ -3403,9 +3403,9 @@
-
+
- R1-R1--2.ibm,update-properties RTAS call must be 4 KB long
@@ -3413,19 +3413,19 @@
may return -3 “Parameter Error”.
-
+
- R1-R1--3.
- The work area on the first call to
+ The work area on the first call to
ibm,update-properties RTAS for a given updated node
- must be formatted as specified in
+ must be formatted as specified in
, else RTAS may return -3
“Parameter Error”.
-
+
- Initial Format of Work Area for
+ Initial Format of Work Area for
ibm,update-properties
@@ -3441,7 +3441,7 @@
- 0x00000000 (Indicates Initial call for specified
+ 0x00000000 (Indicates Initial call for specified
phandle)
@@ -3460,19 +3460,19 @@
-
+
- R1-R1--4.Upon successful return (non-negative status
- value) from
+ value) from
ibm,update-properties the work area must by formatted
- as defined in
+ as defined in
.
-
+
- Return Format of Work Area for
+ Return Format of Work Area for
ibm,update-properties
@@ -3555,7 +3555,7 @@
length (M) of the immediately following property value string
that either starts or continues the update of the property
value with the remainder in the work area of subsequent call(s)
- to
+ to
ibm,update-properties.
Followed by:
@@ -3567,51 +3567,51 @@
-
+
- R1-R1--5.Upon successful return (non-negative status
- value) from
+ value) from
ibm,update-properties when the State Variable had
been 0x00000000, the first updated property descriptor must describe the
fully qualified path name of the node specified by the phandle argument
in the work buffer; the three fields of this updated property descriptor
are:
-
-
+
+
- Property name string is as from
+ Property name string is as from
encode-null
-
+
Value descriptor is the 4 byte binary length of the value
string
-
+
Value string is the fully qualified path name as from the node
name string returned by the open firmware
package-to-path client interface call.
-
+
-
+
- R1-R1--6.
- The work area on subsequent call(s) to
+ The work area on subsequent call(s) to
ibm,update-properties RTAS for a given updated node
- must be formatted as specified in
+ must be formatted as specified in
, else RTAS may return -3
“Parameter Error”.
-
+
- Format of Work Area for Subsequent Calls to
+ Format of Work Area for Subsequent Calls to
ibm,update-properties
@@ -3627,7 +3627,7 @@
- Value from last call to
+ Value from last call to
ibm,update-properties RTAS that returned
status of 1 (12 bytes).
@@ -3642,30 +3642,30 @@
-
+
- R1-R1--7.ibm,update-properties RTAS call, the platform must
- restrict its reported property updates to those specified in
- for the value of the specified
+ restrict its reported property updates to those specified in
+ for the value of the specified
“Scope” argument.
-
+
- R1-R1--8.
- For the
+ For the
ibm,update-properties RTAS call, the platform must
- return a
+ return a
Status of -3 (Parameter Error) for an unrecognized
value of the “Scope” argument.
-
+
- Properties of the Nodes That May Be Reported by
+ Properties of the Nodes That May Be Reported by
ibm,update-properties for a “
Scope”
@@ -3678,8 +3678,8 @@
Scope Value
- Reportable node types (value of
- “name” or
+ Reportable node types (value of
+ “name” or
“device_type” property)
@@ -3914,7 +3914,7 @@
-
+ rtas
@@ -3986,6 +3986,13 @@
+
+
+
+ “ibm,current-associativity-domains”
+
+
+
@@ -4007,7 +4014,7 @@
- children of the
+ children of the
vdevice node
@@ -4119,7 +4126,7 @@
- TLB properties (See
+ TLB properties (See
)
@@ -4325,15 +4332,15 @@
-
+
- Any
+ Any
/rtas node property as defined per LoPAR
remains invariant.
-
+
- Any
+ Any
/rtas node property or definition
extension, except for the value of a function token property*,
may change (provided that the client program has indicated
@@ -4344,7 +4351,7 @@
“ibm,configure-pe”
-
+ *NOTE: This exception mandates that if an RTAS function
token property survives a firmware activation, the token value
of that RTAS function call does not change.
@@ -4357,12 +4364,12 @@
-
+
-
+
ibm,configure-kernel-dump RTAS Call
-
+
This RTAS call is used to register and unregister with the platform
a data structure describing kernel dump information. This dump
information is preserved as needed by the platform in support of a
@@ -4370,15 +4377,15 @@
- R1-R1--1.For the Configure Platform Assisted Kernel Dump
- option: The platform must implement the
+ option: The platform must implement the
ibm,configure-kernel-dump RTAS call using the
- argument call buffer defined by
+ argument call buffer defined by
.
-
+
Argument Call Buffer
ibm,configure-kernel-dump
@@ -4408,7 +4415,7 @@
- Token for
+ Token for
ibm,configure-kernel-dump
@@ -4452,7 +4459,7 @@
When command is 1: Register for future kernel dump,
- points to a structure as defined in
+ points to a structure as defined in
.
@@ -4491,26 +4498,26 @@
-
+
- R1-R1--2.For the Configure Platform Assisted Kernel Dump
option: The work-buffer address and work-buffer-length for the
ibm,configure-kernel-dump RTAS call must point to an
- RMR-memory buffer that contains the structures described in
+ RMR-memory buffer that contains the structures described in
, whenever the command is 1,
register for future kernel dump; otherwise the call may return -3,
“Parameter Error.”
- The Dump Memory Structure specified in
+ The Dump Memory Structure specified in
is passed by the operating
- system during a
+ system during a
ibm,configure-kernel-dump RTAS call. It is also
- reported by the platform using the
+ reported by the platform using the
ibm,kernel-dump RTAS property after a dump has been
initiated.
-
+
Kernel Assisted Dump Memory Structure
@@ -4651,7 +4658,7 @@
Maximum time allowed (milliseconds) after
- Non-Maskable-Interrupt for the OS to call
+ Non-Maskable-Interrupt for the OS to call
ibm,configure-kernel-dumpFunction 2 (unregister) to prevent an
automatic dump-reboot (set to 0 to disable the automatic
@@ -4813,55 +4820,55 @@
-
+
- R1-R1--3.ibm,os-term RTAS call, or on a system reset without
- an
+ an
ibm,nmi-interlock RTAS call, if the platform has a
- dump structure registered through the
+ dump structure registered through the
ibm,configure-kernel-dump call, the platform must
process each registered kernel dump section as required and, when
available, present the dump structure information to the operating system
- through the
+ through the
“ibm,kernel-dump” property, updated with
status for each dump section, until the dump has been invalidated through
- the
+ the
ibm,configure-kernel-dump RTAS call.
-
+
- R1-R1--4.If ibm,configure-kernel-dump RTAS call is made to
register or unregister for a dump while a dump is currently active, the
- platform must return a
+ platform must return a
Status of -9, “Dump Active” indicating
that a dump has been copied by the platform and a call must be made to
complete/invalidate the active dump before another call to register or
unregister a dump can be completed successfully.
-
+
- R1-R1--5.If ibm,configure-kernel-dump RTAS call is made to
register a dump after a dump has already been registered by a call, the
- platform must return a
+ platform must return a
Status of -8, “Dump Already Registered”
unless an intervening call was made to invalidate the previously
registered dump.
-
+
- R1-R1--6.For the Configure Platform Assisted Kernel Dump
@@ -4870,95 +4877,95 @@
existed prior to the os termination or platform reboot.
-
+
- R1-R1--7.For the Configure Platform Assisted Kernel Dump
- Option: The platform must present the RTAS property,
+ Option: The platform must present the RTAS property,
“ibm,configure-kernel-dump-sizes” in the
OF device tree, which describes how much space is required to store dump
data for the firmware provided dump sections, where the firmware defined
dump sections are:
-
-
+
+ 0x0001 = CPU State Data
-
+
0x0002 = Hardware Page Table for Real Mode Region
-
+
-
+
- R1-R1--8.For the Configure Platform Assisted Kernel Dump
- Option: The platform must present the RTAS property,
+ Option: The platform must present the RTAS property,
“ibm-configure-kernel-dump-version” in
the OF device tree.
-
+
- R1-R1--9.For the Configure Platform Assisted Kernel Dump
Option: After a dump registration is disabled (for example, by
- a partition migration operation), calls to
+ a partition migration operation), calls to
ibm,os-term must return to the OS as though a dump
was not registered.Programming Note: The intended flow of interactions
that utilize this call is as follows:
-
-
+
+ The OS registers sections of memory for dump preservation during
OS initialization
-
+
The OS terminates abnormally
-
+
The Platform moves registered sections of memory as instructed
during dump registration.
-
+
The Partition reboots and provides the prior registration data
in the device tree.
-
+
The OS writes the preserved memory regions to disk before using
those memory regions for regular use
-
+
The OS completes/invalidates current dump status.
-
+
-
+
-
+
DMA Window Manipulation Calls
-
+
DMA windows for a PE can be changed by the OS when the platform
implements the Dynamic DMA Windows (DDW) option for a PE. The occurrence
- of the
+ of the
“ibm,ddw-applicable” property in any node
of the OF Device Tree indicates that the platform implements the DDW
option, but that property is required to be in the bridge above a PE in
@@ -4967,52 +4974,52 @@
The platform may implement the DDW RTAS calls even when the OS does
not support these, because they are not required to be used by the OS,
because there is always a default window initially allocated below 4 GB,
- as specified by the
+ as specified by the
“ibm,dma-window” property. During
- partition migration, these RTAS calls may come and go, but so will the
+ partition migration, these RTAS calls may come and go, but so will the
“ibm,ddw-applicable” property as the
nodes in which those are supported come or go.The following is an example of how an OS may grab all DMA window
resources allocated for a PE:
-
+
- If the default window (as specified by the
+ If the default window (as specified by the
“ibm,dma-window” property for the PE) is
- not needed, then call
+ not needed, then call
ibm,remove-pe-dma-window for the PE, specifying the
- default window LIOBN, to make the maximum resources available for the
+ default window LIOBN, to make the maximum resources available for the
ibm,create-pe-dma-window RTAS call.
- Call
- ibm,query-pe-dma-window for the PE to get the
- Windows Available and
- PE TCEs available for the PE. If the
- Windows Available field indicates 1 or more and the
+ Call
+ ibm,query-pe-dma-window for the PE to get the
+ Windows Available and
+ PE TCEs available for the PE. If the
+ Windows Available field indicates 1 or more and the
PE TCEs field is non-zero, then continue.Call ibm,create-pe-dma-window for the PE, specifying the
- size based on the
- PE TCEs field obtained from the
- ibm,query-pe-dma-window RTAS call in step
+ size based on the
+ PE TCEs field obtained from the
+ ibm,query-pe-dma-window RTAS call in step
and on the I/O page size being
specified.
- If the Windows Available field indicated 2 or more in step
- , then go back to step
+ If the Windows Available field indicated 2 or more in step
+ , then go back to step
and repeat, otherwise
finished.
-
+ Software Implementation Note: The general expectation
- is that if the
+ is that if the
“ibm,ddw-applicable” property exists for
a PE, that the OS will be able to generate one or more windows whose
total size is larger than what is available via the default window. This
@@ -5030,136 +5037,136 @@
- R1-R1--1.For the Dynamic DMA Windows (DDW) option: The
- platform must implement all of the following RTAS calls:
- ibm,query-dma-window,
+ platform must implement all of the following RTAS calls:
+ ibm,query-dma-window,
ibm,create-dma-window, and
ibm,remove-dma-window.
-
+
- R1-R1--2.For the Dynamic DMA Windows (DDW) option: The
- platform must provide the
+ platform must provide the
“ibm,ddw-applicable” property in the OF
Device Tree in the bridge above each PE for which the DDW option is
supported.
-
+
- R1-R1--3.For the Dynamic DMA Windows (DDW) option: The
- software must not call the
- ibm,query-dma-window,
+ software must not call the
+ ibm,query-dma-window,
ibm,create-dma-window, or
ibm,remove-dma-window RTAS calls in the absence of
- the
+ the
“ibm,ddw-applicable” property for the PE,
- otherwise the call returns a
+ otherwise the call returns a
Status of -3 (Parameter error), and when the property
- does exist, software must use the token values specified in the
+ does exist, software must use the token values specified in the
“ibm,ddw-applicable” property for these
RTAS calls.
-
+
- R1-R1--4.For the Dynamic DMA Windows (DDW) option: The
platform must provide a default DMA window for each PE, and all of the
following must be true:
-
-
+
+
- The window is defined by the
+ The window is defined by the
“ibm,dma-window” property in the OF
device tree.
-
+
The window is defined with 4 KB I/O pages.
-
+
The window is located entirely below 4 GB.
-
+
-
+
- R1-R1--5.For the Dynamic DMA Windows (DDW) option:
- The platform must remove any DMA windows created by the
+ The platform must remove any DMA windows created by the
ibm,create-pe-dma-window RTAS call for a PE and must
restore the default DMA window (if it was removed) for the PE, as
- originally defined by the
+ originally defined by the
“ibm,dma-window” properties for the PE,
in each of the following cases:
-
-
+
+ On a reboot of the partition
-
+
On a DR isolate operation that encompasses the PE
-
+
-
+
- R1-R1--6.For the Dynamic DMA Windows (DDW) option:
- In Requirement
+ In Requirement
, the platform must provide the
- same LIOBN, location, and size as specified in the
+ same LIOBN, location, and size as specified in the
“ibm,dma-window” property in the OF
Device Tree for the device.
-
+
ibm,query-pe-dma-window
-
+
This RTAS call allows for the discovery of the resources necessary
- to make a successful subsequent call to
+ to make a successful subsequent call to
ibm,create-dma-window.
-
- If the ibm,query-pe-dma-window RTAS call is made with Number Outputs
+
+ If the ibm,query-pe-dma-window RTAS call is made with Number Outputs
equal to 6, and the “ibm,ddw-extensions”
- property does not include list index of 3,
+ property does not include list index of 3,
then the call will return a Status of -3 (Invalid Parameter).
-
+
- R1-R1--1.
- RTAS must implement a
+ RTAS must implement a
ibm,query-pe-dma-window call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
- Argument Call Buffer
+ Argument Call Buffer
ibm,query-pe-dma-window
@@ -5195,7 +5202,7 @@
- Token for
+ Token for
ibm,query-pe-dma-window
@@ -5216,8 +5223,8 @@
- 5 or 6. The value 6 may be used when the ibm,ddw-extensions property
- in the PHB node specified by this call indicates support for a 64-bit value of
+ 5 or 6. The value 6 may be used when the ibm,ddw-extensions property
+ in the PHB node specified by this call indicates support for a 64-bit value of
PE TCEs. See .
@@ -5240,7 +5247,7 @@
Represents the most-significant 32-bits of the Unit ID of
- the PHB that corresponds to the
+ the PHB that corresponds to the
config_addr
@@ -5252,7 +5259,7 @@
Represents the least-significant 32-bits of the Unit ID
- of the PHB that corresponds to the
+ of the PHB that corresponds to the
config_addr
@@ -5278,9 +5285,9 @@
Number of additional DMA windows that can be created for
this PE. If the value is 0 and the default window (as specified
- by the
+ by the
“ibm,dma-window” property for
- the PE) has not been yet removed via the
+ the PE) has not been yet removed via the
ibm,remove-pe-dma-window RTAS call for that
window, and if the default window is not needed, then removal
of the default window makes at least one window
@@ -5292,7 +5299,7 @@
PE TCEs hi
- Represents the most-significant 32-bits of the largest contiguous
+ Represents the most-significant 32-bits of the largest contiguous
block of TCEs allocated specifically for (that is, are reserved for) this PE.
@@ -5301,8 +5308,8 @@
PE TCEs lo
- Represents the least-significant 32-bits of the largest contiguous block
- of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement
+ Represents the least-significant 32-bits of the largest contiguous block
+ of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement
.
@@ -5341,27 +5348,27 @@
-
+
- R1-R1--2.For the Dynamic DMA Windows (DDW) option:
- TCE resources returned in the
- PE TCEs parameter of the
+ TCE resources returned in the
+ PE TCEs parameter of the
ibm,query-dma-window RTAS call must be allocated to
the PE specified by the PE configuration address specified in the call,
- and must be available to a subsequent
+ and must be available to a subsequent
ibm,create-dma-window RTAS call for that PE.
-
+
-
+
ibm,create-pe-dma-window
-
+
This call allows the creation of a new DMA window, given the size
of the DMA window, I/O page size, and the PE to which it is associated.
The return from the call includes the LIOBN of the new DMA window, the
@@ -5369,27 +5376,27 @@
Software Implementation Note: Software is expected to
not attempt to create a DMA window that is larger than possible, or
- create more DMA windows than is possible, otherwise the
- ibm,create-pe-dma-window will return a
+ create more DMA windows than is possible, otherwise the
+ ibm,create-pe-dma-window will return a
Status of -3 (Parameter Error). Thus, the OS is
- expected to use the
+ expected to use the
ibm,query-pe-dma-window first and not ask to create a
window that consumes more resources than those that are available to the
PE.
-
+
- R1-R1--1.For the Dynamic DMA Windows (DDW) option: RTAS must
- implement the
+ implement the
ibm,create-dma-window call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
- Argument Call Buffer
+ Argument Call Buffer
ibm,create-pe-dma-window
@@ -5425,7 +5432,7 @@
- Token for
+ Token for
ibm,create-pe-dma-window
@@ -5468,7 +5475,7 @@
Represents the most-significant 32-bits of the Unit ID of
- the PHB that corresponds to the
+ the PHB that corresponds to the
config_addr
@@ -5480,7 +5487,7 @@
Represents the least-significant 32-bits of the Unit ID
- of the PHB that corresponds to the
+ of the PHB that corresponds to the
config_addr
@@ -5491,7 +5498,7 @@
The value n, where 2
n is the requested I/O page size. Only page
- sizes obtained from the
+ sizes obtained from the
ibm,query-pe-dma-window RTAS call for the
PE are allowed. Values of n from 0-11 are invalid.
@@ -5531,7 +5538,7 @@
LIOBN of the DMA window created by this call, if any. If
- no DMA window was created (that is, if the
+ no DMA window was created (that is, if the
Status is not 0), then this field is
present but not used.
@@ -5543,7 +5550,7 @@
Represents the most-significant 32-bits of the starting
address on the I/O bus for the DMA window created by this call,
- if any. If no DMA window was created (that is, if the
+ if any. If no DMA window was created (that is, if the
Status is not 0), then this field is
present but not used.
@@ -5555,7 +5562,7 @@
Represents the least-significant 32-bits of the starting
address on the I/O bus for the DMA window created by this call,
- if any. If no DMA window was created (that is, if the
+ if any. If no DMA window was created (that is, if the
Status is not 0), then this field is
present but not used.
@@ -5565,58 +5572,58 @@
-
+
- R1-R1--2.
- For the Dynamic DMA Windows (DDW) option: The
- ibm,create-pe-dma-window RTAS call must return a
+ For the Dynamic DMA Windows (DDW) option: The
+ ibm,create-pe-dma-window RTAS call must return a
Status of 0 (Success) only if a window with the
requested attributes is created, and must not create a new window if a
- non-0
+ non-0
Status is returned.
-
+
-
+
ibm,remove-pe-dma-window
-
+
This RTAS call allows for the removal of PE DMA windows, including
- those created with the
+ those created with the
ibm,create-pe-dma-window RTAS call as well as the
- default window specified by the
+ default window specified by the
“ibm,dma-window” property for the PE. All
created DMA windows will be removed by the platform, and the default DMA
window restored, on a partition reboot, on a DR isolate operation (see
- Requirement
- and
+ Requirement
+ and
), or if the last remaining DMA
window for the PE is removed and that window is not the default DMA
- window (see Requirements
- and
+ window (see Requirements
+ and
). After removal of a DMA
- window, software needs to use the
+ window, software needs to use the
ibm,query-pe-dma-window RTAS call to find out what
- resources are available to the PE for subsequent
+ resources are available to the PE for subsequent
ibm,create-pe-dma-window RTAS call.
-
+
- R1-R1--1.For the Dynamic DMA Windows (DDW) option: RTAS must
- implement the
+ implement the
ibm,remove-dma-window call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
-
+
- R1-R1--2.For the Dynamic DMA Windows (DDW) option: The caller
- of the
+ of the
ibm,remove-pe-dma-window RTAS call must assure that
- the TCE table specified by the
+ the TCE table specified by the
LIOBN field does not contain any valid mappings at
the time of the call (that is, that the window is not being used).
-
+
- R1-R1--3.For the Dynamic DMA Windows (DDW) option:
The platform must
- restore the default DMA window for the PE on a call to the
+ restore the default DMA window for the PE on a call to the
ibm,remove-pe-dma-window RTAS call when all of the
following are true:
-
-
+
+ The call removes the last DMA window remaining for the
PE.
-
+
The DMA window being removed is not the default window.
-
+
-
+
- R1-R1--4.For the Dynamic DMA Windows (DDW) option:
- In Requirement
+ In Requirement
, the platform must provide the
- same LIOBN, location, and size as specified in the
+ same LIOBN, location, and size as specified in the
“ibm,dma-window” property in the OF
Device Tree for the PE.
-
+
-
+
Extensions to Dynamic DMA Windows
-
+
Platforms supporting the DDW option implement extensions described
- in this section. These extensions include: adding the
- “ibm,ddw-extensions” property see
+ in this section. These extensions include: adding the
+ “ibm,ddw-extensions” property see
to those nodes that include the
“ibm,ddw-applicable” property, and
implementing the functional extensions specified for the architectural
- level in
- . The
+ level in
+ . The
“ibm,ddw-extensions” property value is a
list of integers the first integer indicates the number of extensions
implemented and subsequent integers, one per extension, provide a value
@@ -5781,7 +5788,7 @@
code was written, and be prepared to operate on back level platforms t at
do not implement all the extensions that were defined when the client
code was written.
-
+
DDW Option Extensions
@@ -5830,29 +5837,29 @@
3
- Value of 1 indicates the OS may invoke RTAS ibm,query-pe-dma-window
+ Value of 1 indicates the OS may invoke RTAS ibm,query-pe-dma-window
with Number Outputs equal to 6. Other values are reserved.
-
+
- R1-R1--1.For compatibility with changing extensions to the Dynamic DMA
Windows (DDW) option: The client program must ignore extensions
- as represented by
+ as represented by
“ibm,ddw-extensions” value list integers
beyond those defined when the client code was written.
-
+
- R1-R1--2.For compatibility with changing extensions to the Dynamic DMA
@@ -5863,30 +5870,30 @@
-
-
+
+
ibm,reset-pe-dma-windows
- The
+ The
ibm,reset-dma-windows call resets the TCE table
- allocation for the PE to its boot time value as communicated in the
+ allocation for the PE to its boot time value as communicated in the
“ibm,dma-window” OF Device Tree property
in the for the PE.
-
+
- R1-R1--1.
- For the Dynamic DMA Windows (DDW) option starting with
+ For the Dynamic DMA Windows (DDW) option starting with
IBM Power Architecture Platform Requirements (PAPR)
- level 2.7: RTAS must implement the
+ level 2.7: RTAS must implement the
ibm,reset-dma-windows call using the argument call
- buffer defined by
+ buffer defined by
.
-
+
-
+
- R1-R1--2.
- For the Dynamic DMA Windows (DDW) option starting with
+ For the Dynamic DMA Windows (DDW) option starting with
IBM Power Architecture Platform Requirements (PAPR)
- level 2.7: The caller of the
+ level 2.7: The caller of the
ibm,reset-pe-dma-windows RTAS call must assure that
- the TCE table(s) assigned to the PE specified by the
+ the TCE table(s) assigned to the PE specified by the
config_addr field contain no valid mappings at the
time of the call (that is, that the window(s) is not being used).
-
+
- R1-R1--3.For the Dynamic DMA Windows (DDW) option starting with
IBM Power Architecture Platform Requirements (PAPR)
- level 2.7: On a call to
+ level 2.7: On a call to
ibm,restore-pe-dma-windows, the platform must
- restore the default DMA window per the values provided in the
+ restore the default DMA window per the values provided in the
“ibm,dma-window” Tree property
in the for the PE (same LIOBN, location, and size).
-
-
+
+
-
+
-
+