From ca97246a2b0cd458309b23d1b206d04b45ffc2b0 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Tue, 7 Apr 2020 14:13:26 -0500 Subject: [PATCH] ibm,current-associativity-domains property Signed-off-by: Jeff Scheel --- DeviceTree/ch_devtree_system.xml | 16 + Platform/ch_numa.xml | 498 ++++----- RTAS/sec_rtas_get_indices.xml | 1647 +++++++++++++++--------------- 3 files changed, 1095 insertions(+), 1066 deletions(-) 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.
- Example NUMA configuration with - domains and corresponding <emphasis role="bold"><literal>“ibm,associativity”</literal></emphasis> + <title>Example NUMA configuration with + domains and corresponding <emphasis role="bold"><literal>“ibm,associativity”</literal></emphasis> values @@ -67,231 +67,231 @@ xml:lang="en">
- - 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 0 When 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 1 When 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 @@
- + <emphasis>ibm,get-indices</emphasis> 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 . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,get-indices</emphasis> @@ -100,7 +100,7 @@ - Token for + Token for ibm,get-indices @@ -209,150 +209,150 @@
- 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 @@
<emphasis>ibm,set-dynamic-indicator</emphasis> 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 + <title>Argument Call Buffer <emphasis>ibm,set-dynamic-indicator</emphasis> @@ -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 - + - +
- +
<emphasis>ibm,get-dynamic-sensor-state</emphasis> 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 - + - +
- +
<emphasis>ibm,get-vpd</emphasis> RTAS Call This 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 + <title>Argument Call Buffer <emphasis>ibm,get-vpd</emphasis> @@ -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 . - + <emphasis>ibm,manage-storage-preservation</emphasis> 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 @@
- +
<emphasis>ibm,lpar-perftools</emphasis> 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 + <title>Argument Call Buffer <emphasis>ibm,lpar-perftools</emphasis> @@ -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 @@
- +
<emphasis>ibm,suspend-me</emphasis> 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 . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,suspend-me</emphasis> @@ -1946,7 +1946,7 @@ - Token for + Token for ibm,suspend-me @@ -1994,173 +1994,173 @@
- + - 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 @@ - +
<emphasis>ibm,update-nodes</emphasis> 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 <emphasis>ibm,update-nodes</emphasis> @@ -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 + <title>Initial Format of Work Area for <emphasis>ibm,update-nodes</emphasis> @@ -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 + <title>Format of Work Area for <emphasis>ibm,update-nodes</emphasis> @@ -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 + <title>Format of Work Area for Subsequent Calls to <emphasis>ibm,update-nodes</emphasis> @@ -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 + <title>Nodes That May be Reported by <emphasis>ibm,update-nodes</emphasis> for a Given Value of the “ <emphasis>Scope</emphasis>” 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 @@ - +
<emphasis>ibm,update-properties</emphasis> 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 <emphasis>ibm,update-properties</emphasis> @@ -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 + <title>Initial Format of Work Area for <emphasis>ibm,update-properties</emphasis> @@ -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 + <title>Return Format of Work Area for <emphasis>ibm,update-properties</emphasis> @@ -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 + <title>Format of Work Area for Subsequent Calls to <emphasis>ibm,update-properties</emphasis> @@ -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 + <title>Properties of the Nodes That May Be Reported by <emphasis>ibm,update-properties</emphasis> for a “ <emphasis>Scope</emphasis>” @@ -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 @@ - + - +
<emphasis>ibm,configure-kernel-dump</emphasis> 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 <emphasis>ibm,configure-kernel-dump</emphasis> @@ -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-dump Function 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. - +
<emphasis>ibm,query-pe-dma-window</emphasis> - + 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 + <title>Argument Call Buffer <emphasis>ibm,query-pe-dma-window</emphasis> @@ -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. - +
- +
<emphasis>ibm,create-pe-dma-window</emphasis> - + 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 + <title>Argument Call Buffer <emphasis>ibm,create-pe-dma-window</emphasis> @@ -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. - +
- +
<emphasis>ibm,remove-pe-dma-window</emphasis> - + 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 . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,remove-pe-dma-window</emphasis> @@ -5652,7 +5659,7 @@ - Token for + Token for ibm,remove-pe-dma-window @@ -5706,70 +5713,70 @@
- + - 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 @@ - - + +
<emphasis>ibm,reset-pe-dma-windows</emphasis> - 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 . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,reset-pe-dma-windows</emphasis> @@ -5922,7 +5929,7 @@ - Token for + Token for @@ -5995,41 +6002,41 @@
- + - 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). - - + +
- +
- +