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 “ibm,environmental-sensor” properties). This call also allows discontiguous indices for a particular indicator or 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 . 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 ibm,get-indices for different indicator or sensor types. Other standard RTAS locking rules apply. R1--1. For all DR options: The RTAS function ibm,get-indices must implement the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,get-indices Number Inputs 5 Number Outputs 2 Indicator or Sensor 0: indicator of given type 1: sensor of given type Indicator Type Indicator or sensor type (for example, 9006, 9007) Work Area Address Address of work area Work Area Size Size of work area Starting Number Integer representing first indicator number to return Out Status -1: Hardware error -3: Indicator type not supported -4: Optional: Indicator list changed, start again 0: Success 1: More data available; call again 990x:Extended Delay where x is a number 0-5 (see text below) Next Starting Number Integer to use as the Starting Number parameter on the next call, or 1 if no more calls are required 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 ibm,get-indices with the same Starting Number and Indicator Type. However, software may issue the ibm,get-indices call again either earlier or later than this. R1--2. The OS must not interleave calls to ibm,get-indices for different indicator or sensor types. R1--3. On the first call to get a particular Indicator Type, the caller must provide a Starting Number of 1 (32-bit integer) R1--4. 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--5. When calling ibm,get-indices with a Starting Number of 1, a previously returned Next Starting Number value must be discarded. R1--6. Optionally, if firmware detects a change in 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--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--8. If the Status returned is 1 (more data available, call again), 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--9. 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--10. 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--11. 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--12. The ibm,get-indices RTAS call must only return the indicator or sensor indices to which the caller has authorized access at the time of the call. 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--14. When the platform supports the ibm,get-indices RTAS call, the device tree must include the “ibm,get-indicator-indices-types” property in the /rtas node if the call is to be used for getting indicator information and must include the “ibm,get-sensor-indices-types” property in the /rtas node if the call is to be used for getting sensor information. R1--15. 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 “rtas-indicators” property. R1--16. 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 “rtas-sensors” property. R1--17. When an environmental sensor token is provided in the “ibm,get-sensor-indices-types” property, 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--18. When the value of 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--19. The OS must not call get-sensor-state or get-indicator with an index value of 0xFFFFFFFF.

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--1. Platforms that implement any indicators that are identified by location code instead of index (see Requirement ) must implement the ibm,set-dynamic-indicator RTAS function. R1--2. The RTAS function ibm,set-dynamic-indicator must implement the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,set-dynamic-indicator Number Inputs 3 Number Outputs 1 Indicator Token defining the indicator 9006: Error Log 9007: Identify Indicator State Desired new state; see . Location Code Address Real or Logical address of a location code string, in the format defined by Requirement Out Status -1: Hardware error -2: Busy, try again later -3: No such indicator 0: Success 990x: Extended delay, where x is a number between 0 and 5, as described below When 990x Status is returned, it is suggested that software delay for 10 raised to the power x milliseconds (where x is the last digit of the 990x return code), before calling ibm,set-dynamic-indicator with the same indicator type and location code. However, software may call ibm,set-dynamic-indicator again either earlier or later than this. R1--3. 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 ibm,set-dynamic-indicator call. R1--4. 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--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--6. The platform must not modify the location code string. R1--7. The OS must only use this call for indicators which have been provided by the ibm,get-indices RTAS call with an index value of 0xFFFFFFFF. R1--8. Platforms must identify all indicators except types 9006 and 9007 by index. R1--9. 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

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--1. Platforms that implement any sensors that are identified by location code instead of index (see Requirement ) must implement the ibm,get-dynamic-sensor-state RTAS function. R1--2. The RTAS function ibm,get-dynamic-sensor-state must implement the argument call buffer defined by .   Parameter Type Name Values In Token Token for ibm,get-dynamic-sensor-state   Number Inputs 2   Number Outputs 2   Sensor Token defining the sensor   Location Code Address Real or Logical address of a location code string, in the format defined by Requirement Out Status -1: Hardware error -2: Busy, try again later -3: No such indicator 0: Success 990x: Extended delay, where x is a number between 0 and 5, as described below   State Current state of the sensor as defined in the Defined Values column of . When 990x Status is returned, it is suggested that software delay for 10 raised to the power x milliseconds (where x is the last digit of the 990x return code), before calling ibm,get-dynamic-sensor-state with the same indicator type and location code. However, software may call ibm,get-dynamic-sensor-state again either earlier or later than this. R1--3. 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 ibm,get-dynamic-sensor-state call. R1--4. The work area must be contiguous in real memory and must reside below 4GB. 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--6. The platform must not modify the location code string. R1--7. The OS must only use this call with sensors which have been provided by the ibm,get-indices RTAS call with an index value of 0xFFFFFFFF. R1--8. The platform must use the ibm,get-dynamic-sensor-state RTAS call only for dynamic sensor types of 9004, 9006 and 9007. 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

This RTAS call allows for collection of VPD that changes after OS boot time (after the initial reporting in the OF device tree). When this call is implemented, there is no overlap between what is reported in the device tree and what is reported with this RTAS call. Also, when this RTAS call is implemented, all VPD, except PCI and I/O device VPD, which is dynamically changed during OS run time is reported with this call and not via the “ibm,vpd” property in the OF device tree. 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 ibm,get-vpd RTAS call. R1--2. The RTAS function ibm,get-vpd must implement the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,get-vpd Number Inputs 4 Number Outputs 3 Pointer to Location Code Real address of NULL-terminated string, contiguous in real memory and below 4GB, which is the location code of the FRU for which to obtain the VPD. When this parameter references a NULL string the VPD for all location codes is returned. Work Area Address Address of work area Work Area Size Size of work area Sequence Number Integer representing the sequence number of the call. First call in sequence starts with 1, following calls (if necessary) use the Next Sequence Number returned from the previous call. Out Status -1: Hardware error -3: Parameter error -4: Optional: VPD changed, start again 0: Success 1: More data available; call again 990x: Extended Delay where x is a number 0-5 (see text below) Next Sequence Number Return this integer as the Sequence Number parameter on the next call to continue the sequence, or 1 if no more calls are required Bytes Returned Integer representing the number of valid bytes returned in the work area. 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 ibm,get-vpd with the same input parameters. However, software may issue the ibm,get-vpd call again either earlier or later than this. R1--3. On the first call to ibm,get-vpd for a particular VPD gathering operation, the caller must provide a Sequence Number of 1 (32-bit integer) R1--4. 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 ibm,get-vpd cannot be interleaved by multiple 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 Status of 1, and the subsequent call has not yet been made) then the call sequence on processor “A” is abandoned. 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 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 Status of -4. 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 “ibm,vpd” property of the OF device tree. R1--7. Each stanza of the returned data must include the YL (location code) keyword. R1--8. If the ibm,get-vpd RTAS call is implemented, then the platform must not provide the “ibm,vpd” or “ibm,loc-code” properties in the OF device tree root node. R1--9. If the ibm,get-vpd RTAS call is implemented, then any VPD which may change after OS boot must be reported via the ibm,get-vpd RTAS call. R1--10. 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 Next Sequence Number integer from the previously returned call. R1--11. If a Status of anything other than 0 or 1 is returned, the contents of the work area is not defined. R1--12. The work area must be contiguous in real memory and must reside below 4GB. 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 Sequence Number). R1--14. The location code referenced by the Pointer to Location Code parameter must reside in contiguous real memory below an address of 4GB. R1--15. If the ibm,get-vpd RTAS call is implemented, then firmware must supply the “ibm,vpd-size” property in the /rtas node, the value of which is a single cell, 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 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 firmware is unable to estimate this size, it may return a value of 0x0 to indicate that no estimate is available. Software Implementation Notes: An OS should be prepared for older versions of firmware where the “ibm,vpd-size” property is not provided. Each stanza of the returned data must include the YL (location code) keyword.

Platforms may optionally preserve selected regions of storage (LMBs) across client program boot cycles. for more information. R1--1. For the Storage Preservation option: The platform must implement the ibm,manage-storage-preservation RTAS argument call buffer as defined by . Parameter Type Name Values In Token Token for ibm,manage-storage-preservation Number Inputs 3 Number Outputs 2 Subfunction 0 = unused (return -3) 1 = Register specified LMB for preservation 2 = Query preservation state of specified LMB 3 = Deregister for preservation Specific LMB 4 = Deregister for preservation all caller’s LMBs. All other values reserved (return -3) Reg High The high order 32 bits of the LMB's “reg” property (Subfunctions 1-3) Reg Low The low order 32 bits of the LMB's “reg” property (Subfunctions 1-3) Out Status -1: Hardware error -2: Busy -3: Parameter error (Subfunction or Reg invalid; or Reg for a non-preservable LMB) 0: Success 990x: Extended delay where x is a number 0-5 Preservation state If Status= Success, the current preservation state of specified LMB (Subfunctions 1-3) R1--2. For the Storage Preservation option: The platform 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--3. For the Storage Preservation option: The value of the “ibm,preservable” property for the first LMB must be 0 (cannot be preserved). R1--4. For the Storage Preservation option: The platform must not preserve the first LMB, thus must indicate a value of 0 for the “ibm,preservable” property for the first LMB. R1--5. For the Storage Preservation option: The platform 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--6. For the Storage Preservation option: The platform, on 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--7. For the Storage Preservation option: If the client program registered an LMB for preservation, the platform must preserve the LMB's storage state across client program reboots. R1--8. For the Storage Preservation option: The platform, on 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 assumed by the OS.

This RTAS call provides access to platform-level facilities for performance tools running in a partition on an LPAR system. Platforms may require platform-specific tools, beyond the scope of this architecture, to make this call available. R1--1. For the Performance Tool Support option: The platform must implement the LPAR option. R1--2. For the Performance Tool Support option: RTAS must implement the ibm,lpar-perftools call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,lpar-perftools Number Inputs 5 Number Outputs 2 Subfunction 1: Convert hypervisor IAR value to method name. Work Area Address High Most significant 32 bits of real address of work area Work Area Address Low Least significant 32 bits of real address of work area Work Area Size Size of work area in bytes Sequence Number Integer representing the sequence number of this call. First call in sequence starts with 1, following calls (if necessary) use the Next Sequence Number returned from the previous call. Out Status -1: Hardware Error -2: Busy -3: Parameter Error (Subfunction invalid, invalid work area address, invalid work area size) -9002: Partition does not have authority to perform this function -5: Buffer was too small to supply requested data 0: Success 990x: Extended delay Next Sequence Number Return this integer as the Sequence Number parameter on the next call, or 1 if no more calls are required. 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 ibm,lpar-perftools call with the same input parameters. However, software may issue the ibm,lpar-perftools call again earlier or later than this. R1--3. 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 address from the start of the hypervisor function, method or module, followed by a NULL-terminated text string containing the name of the hypervisor function, method or module. If the address is not a valid address in the hypervisor, on output the buffer must contain 0x0 (8 bytes) followed by a NULL-terminated text string indicating that the address was not valid. R1--4. For the Performance Tool support option: The work area must reside in contiguous memory. R1--5. 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--6. For the Performance Tool Support option: A partition must have at most one call to this function in process at a given time. This means that if one processor in the partition initiates this call, receives a Busy or Extended Delay return, and then another processor calls this function with a sequence number of 1, a subsequent call using the Next Sequence Number returned to the first processor results in a Parameter Error return code.

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 ) to deactivate other processing threads. Processing treads may exit H_JOIN due to an 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 sections on "Partition Migration" and "Partition Hibernation"). The ibm,suspend-me RTAS call returns only on the calling 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 ) 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 ). Also during suspension, some system parameters may have changed. See , for details. The OS may want to re-scan selected system parameters. R1--1. For the Partition Suspension option: The platform must implement the Logical Partitioning option (see ) . R1--2. For the Partition Suspension option: RTAS must implement the ibm,suspend-me call within a logical partition using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,suspend-me Number Inputs 0 Number Outputs 1 Out Status 9000: Suspension Aborted 0: Success -- expected return on function resume -1: Hardware Error   -9004: Partition not suspendable -9005: Multiple processor threads active -9006: Outstanding COP Operations R1--3. 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--4. 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--5. For the Partition Suspension option: The platform must implement the Thread Join option (see ). 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 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 . 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 ibm,suspend-me RTAS call. R1--8. For the Partition Suspension option: The platform must support the “update OF tree” option. R1--9. For the Partition Suspension option: The platform must support the “Partner partition suspended” CRQ Transport Event (See ). R1--10. 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 ibm,suspend-me. 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--11. 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--12. For the Partition Suspension option: The platform must implement the H_ENABLE_CRQ hcall() using the syntax and semantics described in . R1--13. For platforms that implement the Partition Suspension and VSCSI options: The “compatible” property of the 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--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 ibm,suspend-me. R1--15. For the Partition Suspension option: The platform must implement the LRDR option (See ). R1--16. For the Partition Suspension option: The logical 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--17. For the Partition Suspension option: The platform must not change the support for a system parameter during suspension. NOTE: If RTAS returns a status of -3 (System parameter not supported) prior to suspension, it returns a Status of -3 for accesses to that same system parameter after suspension. Similarly if RTAS does not return a Status of -3 prior to suspension for a given system parameter, it does not do so after suspension. R1--18. For the Partition Suspension option: The platform must limit the system parameters that change values during suspension to those specified in (all system parameters not specified are preserved). R1--19. For the Partition Suspension option: The platform must preserve up to the first 32 SLB entries for each partition processor during the suspension. Other SLB entries are subject to loss. R1--20. For the Partition Suspension option with the Platform 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 Parameter Token Name   0-15 HMC   18-19 Legacy processor CoD   20   SPLPAR characteristics Only specified SPLPAR keywords may change value   DesiredEntitledCapacity   DesiredMemory   DesiredNumberOfProcessors   DesiredVariableCapacityWeight   DispatchWheelRotationPeriod   MinimumEntitledCapacityPerVP Platform prevents migration where current Entitled Capacity/VCPU ratio would be below the target's minimum. MaximumPlatformProcessors   22 platform_auto_power_restart   23 sp-remote-pon   24 sp-rb4-pon   25 sp-snoop-str   30 sp-call-home   31 sp-current-flash-image   33 epow3-quiesce-time   34 memory-preservation-boot-time   35 SCSI initiator identifier   36 AIX support The keyword “support” may not change to the value “no” for an AIX client. 37 enhanced processor CoD   38 enhanced memory CoD   39 CoD Options   41 firmware boot options   43 processor module information  

This RTAS call is used to determine which device tree nodes have changed due to a massive platform reconfiguration such as when the partition is migrated between machines. Differing platform reconfigurations are expected to potentially result in different sets of nodes being updated; the “scope” argument communicates what set of changes are to be reported. The work area is a 4 KB naturally aligned area of storage below the first 4 GB; as such, it may not be large enough to contain the reports of all changed nodes. The status value of 1 is used to inform the caller that there are more updates to report and that it will have to call the 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 with the information it needs to continue from where the previous call ended. Upon return, the work area contains, in addition to the state variable, zero or more operation lists, and logically ends with a terminator (4 byte word naturally aligned containing 0x00000000). An operation list consists of an operator (4 bytes naturally aligned) and zero or more (up to a the maximum number of 4 byte locations remaining in the work area) operands, each 4 bytes long. An operator consists of a single byte opcode followed by 3 bytes encoded with the binary value of the number of operands that follow. An operator with an operand length field of zero performs no operation, and the opcode of zero is reserved for the terminator -- thus the terminator can be considered a special encoding of a no-op operator. The opcode of 0x01 is used for deleted nodes -- the operands are the phandle values for the deleted nodes. The opcode of 0x02 is used for updated nodes -- the operands are the phandle values for the updated nodes. The updated 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 phandle value denotes the parent node of the node to 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 “ibm,phandle” property. R1--1. For the Update OF Tree option: The platform must include the “ibm,phandle” property in all OF nodes specified in . R1--2. For the Update OF Tree option: The platform must implement the ibm,update-nodes RTAS call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,update-nodes Number Inputs 2 Number Outputs 1 Work Area Address 32 bit real address of work area Scope Values per . Out Status -1: Hardware Error -2: Busy -3: Parameter Error (Purpose does not match the current partition state) 0: Success 1: More nodes updated -- call again R1--3. ibm,update-nodes RTAS call work area must be 4 KB long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS may return -3 “Parameter Error”. R1--4. ibm,update-nodes RTAS for a given value of “ Scope” must be formatted as specified in , else RTAS may return -3 “Parameter Error”. 0x00000000 (State Variable indicates Initial call for specified Scope) 12 bytes of 0x00 (reserved) Don’t Care . . . R1--5. Upon successful return (non-negative status value) from ibm,update-nodes the work area must by formatted as defined in . (Note each entry in is 4 bytes long.) State Variable (4 Bytes) 12 bytes of 0x00 (reserved) 0 or more operation lists . . . Terminator (0x00000000) R1--6. 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--7. 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--8. 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--9. The opcode of 0x01 in an ibm,update-nodes RTAS call operation list must be used to denote node deletions. R1--10. The operands for opcode 0x01 in an ibm,update-nodes RTAS call operation list must be the phandle values for the deleted nodes. R1--11. The opcode of 0x02 in an ibm,update-nodes RTAS call operation list must be used to denote updated nodes. R1--12. 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 ibm,update-properties RTAS call argument to obtain the changed properties of the updated node. R1--13. The opcode of 0x03 in an ibm,update-nodes RTAS call operation list must used for the added nodes. R1--14. 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 ibm,configure-connector RTAS call argument to obtain the contents of the added node respectively. R1--15. 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--16. 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--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 , else RTAS may return -3 “Parameter Error”. Value of the 1st 16 bytes of the returned work area from last call to ibm,update-nodes RTAS that returned status of 1. Don’t Care . . . R1--18. The “Scope” argument for the ibm,update-nodes RTAS call must be one of the values specified in the scope value column of , else RTAS may return -3 “Parameter Error”. R1--19. 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 “Scope” argument. Scope Value Reportable node types (value of “name” or “device_type” property) Supported Opcodes Negative values: Platform Resource Reassignment events as from event-scan RTAS cpu 0x02 memory 0x02 ibm,dynamic-reconfiguration-memory 0x02 ibm,plaform-facilities 0x01-0x03 ibm,random-v# 0x01-0x03 ibm,compression-v# 0x01-0x03 ibm,encryption-v# 0x01-0x03 ibm,memory-utilization_instrumentation-v# 0x01-0x03 1 Partition Migration / Hibernation root 0x02 openprom 0x02 rtas 0x02 vdevice 0x02 cpu 0x02 cache 0x01-0x03 options 0x02 memory 0x02 ibm,dynamic-reconfiguration-memory <all> ibm,platform-facilities 0x01-0x03 ibm,random-v# 0x01-0x03 ibm,compression-v# 0x01-0x03 ibm,encryption-v# 0x01-0x03 ibm,memory-utilization_instrumentation-v# 0x01-0x03 2 Activate Firmware rtas 0x02

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 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 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 properties updated -- call again”. On the first call, the second word of the work area contains the value 0 specifying that the RTAS call 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 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 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 a positive number. When the updated property value descriptor contains either the initial or interim data for the property value, the updated property string length field is a negative number denoting the twos complement of the length of the updated property string contained in the work area. The data value strings for a given property name are 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 || name property value || @ unit address) even if there has been no change. R1--1. For the Update OF Tree option: The platform must implement the ibm,update-properties RTAS call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,update-properties Number Inputs 2 Number Outputs 1 Work Area Address 32 bit real address of work area Scope Values per . Out Status -1: Hardware Error -2: Busy -3: Parameter Error (Purpose does not match the current partition state) 0: Success 1: More properties updated -- call again R1--2. ibm,update-properties RTAS call must be 4 KB long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS may return -3 “Parameter Error”. R1--3. The work area on the first call to ibm,update-properties RTAS for a given updated node must be formatted as specified in , else RTAS may return -3 “Parameter Error”. phandle of updated node containing updated properties to be reported (4 bytes) 0x00000000 (Indicates Initial call for specified phandle) 8 bytes of 0x00 (reserved) Don’t Care . . . R1--4. Upon successful return (non-negative status value) from ibm,update-properties the work area must by formatted as defined in . Description Comments phandle of updated node containing updated properties to be reported. 4 Bytes State Variable (to be returned if status argument value = 1) 4 Bytes Reserved 8 bytes Number of properties reported in the work area 4 Bytes The number (N) of updated property value descriptors that follow -- see below N updated property value descriptors Each updated property value descriptor is formatted as:   Null terminated string indicating the name of the updated property. followed by: Value Descriptor -- 4 Bytes decoded as   0x00000000 Name only property ( “encode-null”) no value follows   0x80000000 The property is to be deleted no value follows   Other positive values are the length (M) of the immediately following property value string that completes the update of the property value.   Other negative values are the twos complement of the 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 ibm,update-properties.   Followed by: 0-M bytes of property value string. R1--5. Upon successful return (non-negative status 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 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--6. The work area on subsequent call(s) to ibm,update-properties RTAS for a given updated node must be formatted as specified in , else RTAS may return -3 “Parameter Error”. phandle of updated node containing updated properties to be reported (4 Bytes) Value from last call to ibm,update-properties RTAS that returned status of 1 (12 bytes). Don’t Care . . . 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 “Scope” argument. R1--8. For the ibm,update-properties RTAS call, the platform must return a Status of -3 (Parameter Error) for an unrecognized value of the “Scope” argument. Scope Value Reportable node types (value of “name” or “device_type” property) Property Name All negative values: Resource Reassignment events as from event-scan RTAS /memory “ibm,associativity” ibm,dynamic-reconfiguration-memory “ibm,dynamic-memory” “ibm,dynamic-memory-v2” cpu “ibm,associativity” ibm,random-v# <all> ibm,compression-v# <all> ibm,encryption-v# <all> ibm,memory-utilization_instrumentation-v# <all> 1 Partition Migration / Hibernation root “ibm,model-class” “clock-frequency” “ibm,extended-clock-frequency” “model” “compatible” “name” “system-id” “ibm,partition-no” “ibm,drc-info” “ibm,drc-indexes” “ibm,drc-names” “ibm,drc-power-domains” “ibm,drc-types” “ibm,aix-diagnostics” “ibm,diagnostic-lic” “ibm,platform-hardware-notification” “ibm,ignore-hp-po-fails-for-dlpar” “ibm,managed-address-types” “ibm,service-indicator-mode” openprom “model” rtas “power-on-max-latency” “ibm,associativity-reference-points” “ibm,max-associativity-domains” “ibm,configure-kernel-dump” “ibm,configure-kernel-dump-sizes” “ibm,configure-kernel-dump-version” “ibm,read-slot-reset-state-functions” “ibm,configure-pe” “ibm,change-msix-capable” “ibm,current-associativity-domains” vdevice “ibm,drc-names” “ibm,drc-info” children of the vdevice node “ibm,loc-code” 1 Partition Migration / Hibernation   cpu “name” “d-cache-sets” “d-cache-size” “i-cache-sets” “i-cache-size” “bus-frequency” “ibm,extended-bus-frequency” “ibm,extended-clock-frequency” “clock-frequency” “timebase-frequency” “l2-cache” “performance-monitor” “ibm,associativity” TLB properties (See ) “slb-size” “ibm,tbu40-offset” “ibm,pi-features” “ibm,spurr” “ibm,pa-optimizations” “ibm,dfp” (sign bit only) “ibm,sub-processors” cache “d-cache-sets” “d-cache-size” “i-cache-sets” “i-cache-size” l2-cache options “ibm,dasd-spin-interval” memory “ibm,associativity” ibm,dynamic-reconfiguration-memory “ibm,associativity-lookup-arrays” “ibm,dynamic-memory” “ibm,dynamic-memory-v2” only the associativity list index fields “ibm,memory-preservation-time” /chosen “ibm,architecture-vec-5” byte 3 (I/O Super Page Option support parameters) 1 Partition Migration / Hibernation   ibm,random-v# <all> ibm,compression-v# <all> ibm,encryption-v# <all> ibm,memory-utilization_instrumentation-v# <all> 2 Activate Firmware rtas Any /rtas node property as defined per LoPAR remains invariant. 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 support for such property or definition extension) including the following: “ibm,read-slot-reset-state-functions” “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.

This RTAS call is used to register and unregister with the platform a data structure describing kernel dump information. This dump information is preserved as needed by the platform in support of a platform assisted kernel dump option. R1--1. For the Configure Platform Assisted Kernel Dump option: The platform must implement the ibm,configure-kernel-dump RTAS call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,configure-kernel-dump Number Inputs 3 Number Outputs 1 Command 1: Register for future kernel dump 2: Unregister for future kernel dump 3: Complete/Invalidate current kernel dump Work_buffer_address When command is 1: Register for future kernel dump, points to a structure as defined in . Work_buffer_length Length of Kernel Dump Memory Structure when defined above Out Status 0: Success -1: Hardware Error -2: Busy -3: Parameter Error -9: Dump Already Registered -10: Dump Active 990x:Extended Delay 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 , whenever the command is 1, register for future kernel dump; otherwise the call may return -3, “Parameter Error.” The Dump Memory Structure specified in is passed by the operating system during a ibm,configure-kernel-dump RTAS call. It is also reported by the platform using the ibm,kernel-dump RTAS property after a dump has been initiated. Header Offset Number of Bytes Value 0x0 4 Dump Format Version = 0x00000001 0x4 2 Number of Kernel Dump Sections 0x6 2 Dump Status Flags A bit mask with value 0x8000 = Dump performed (Set to 0 by caller of the ibm,configure-kernel-dump call) 0x4000 = Dump was triggered by the previous system boot (set by platform) 0x2000 = Dump error occurred (set by platform) All other bits reserved 0x8 4 Offset to first Kernel Dump Section, offset from the beginning of the Structure 0xc 4 Number of bytes in a block of the dump-disk, if data to be written to a dump-disk, If not, should be set to 0 (indicating the no disk dump option.) 0x10 8 Starting block# offset on dump-disk (set to 0 for the no disk dump option) 0x18 8 Number of blocks on dump-disk usable for dump (set to 0 for the no disk dump option) 0x20 4 Offset from start of structure to a Null-terminated Dump-disk path string (set to 0 for the no disk dump option) 0x24 4 Maximum time allowed (milliseconds) after 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 dump-reboot function) Dump-disk Path String Offset specified above Varies Null-terminated Dump-disk path string specifying the dump-disk. If no disk dump option is indicated, this section is not included. First Kernel Dump Section Offset specified above 4 Dump Request Flags: A bit-mask Bit 0x00000001 When set, firmware to copy source data to partition memory. This option must be selected if no disk dump option is indicated. All other bit values reserved Section Start+4 2 Source Data type, describes section of dump memory being described 0x0001 = CPU State Data 0x0002 = Hardware Page Table for Real Mode Region 0x0011 = Real Mode Region 0x0012 = Dump OS identified string (identifies that the dump is for a particular OS type and version) 0x0100 - 0xFFFF OS defined source types All Other values reserved Section Start+6 2 Dump Error Flags (set by platform) Bit mask 0x8000 = Invalid section data type 0x4000 = Invalid source address 0x2000 = Requested section length exceeds source 0x1000 = Invalid partition destination address 0x0800 = Partition memory destination too small Section Start+8 8 Source address (logical address if section came from partition memory, or byte offset if section is platform memory) Section Start+16 8 Requested data length, represents number of bytes to dump Section Start+24 8 Actual data length, number of bytes dumped Section Start+32 8 Destination address, logical address used for sections not written to disk by the platform, always required for a Real mode region section and for all sections when the no disk dump option is used. Subsequent Sections Previous Section Start+40 Start of Next Section A total of up to nine additional 40 bytes sections with values as described in the First Section may be specified so long as the entire structure does not exceed 512 bytes for version 1. R1--3. ibm,os-term RTAS call, or on a system reset without an ibm,nmi-interlock RTAS call, if the platform has a 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 “ibm,kernel-dump” property, updated with status for each dump section, until the dump has been invalidated through the ibm,configure-kernel-dump RTAS call. 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 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--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 Status of -8, “Dump Already Registered” unless an intervening call was made to invalidate the previously registered dump. R1--6. For the Configure Platform Assisted Kernel Dump Option: Partition memory not specifically mentioned in the call structure must be preserved by the platform at the same location as existed prior to the os termination or platform reboot. R1--7. For the Configure Platform Assisted Kernel Dump 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--8. For the Configure Platform Assisted Kernel Dump Option: The platform must present the RTAS property, “ibm-configure-kernel-dump-version” in the OF device tree. 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 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 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 “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 order for the DDW RTAS call to be applicable for the PE. That is, DDW may be applicable to some PEs in a platform and not for others. 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 “ibm,dma-window” property. During 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 “ibm,dma-window” property for the PE) is 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 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 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 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 and repeat, otherwise finished. Software Implementation Note: The general expectation 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 requires either additional TCEs being available or that I/O page sizes other than 4 KB are available and the PE can use the largest I/O page size (the default window using only the 4 KB I/O page size). If not, then removing the default window would only allow re-allocation of the same size window at a different bus address (that is, same number of TCEs and same I/O page size). However, it may be possible for this to happen, in which case the platform may indicate that DDW is available to a PE, but removal of the default window will only allow creation of the same size window. An example is when a larger I/O page size is available but only the TCEs in the default window are available, and the PE cannot make use of the larger page size. R1--1. For the Dynamic DMA Windows (DDW) option: The platform must implement all of the following RTAS calls: ibm,query-dma-window, ibm,create-dma-window, and ibm,remove-dma-window. R1--2. For the Dynamic DMA Windows (DDW) option: 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--3. For the Dynamic DMA Windows (DDW) option: The 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 “ibm,ddw-applicable” property for the PE, 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 “ibm,ddw-applicable” property for these RTAS calls. 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 “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--5. For the Dynamic DMA Windows (DDW) option: 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 “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--6. For the Dynamic DMA Windows (DDW) option: In Requirement , the platform must provide the same LIOBN, location, and size as specified in the “ibm,dma-window” property in the OF Device Tree for the device.

This RTAS call allows for the discovery of the resources necessary 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 equal to 6, and the “ibm,ddw-extensions” property does not include list index of 3, then the call will return a Status of -3 (Invalid Parameter). R1--1. RTAS must implement a ibm,query-pe-dma-window call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,query-pe-dma-window Number Inputs 3 Number Outputs 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 . Config_addr PE configuration address (Register fields set to 0) PHB_Unit_ID_Hi Represents the most-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr PHB_Unit_ID_Low Represents the least-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr Out Status 0: Success -1: Hardware Error -3: Parameter error Windows Available 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 “ibm,dma-window” property for 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 available. PE TCEs hi Represents the most-significant 32-bits of the largest contiguous block of TCEs allocated specifically for (that is, are reserved for) this PE. 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 . IO Page Sizes I/O Page Size Support. I/O page sizes supported for this PE. This is a bit significant field, defined as follows: Bits 0 - 23 reserved 24 = 16 GB page size supported 25 = 256 MB page size supported 26 = 128 MB pages supported 27 = 64 MB page size supported 28 = 32 MB page size supported 29 = 16 MB page size supported 30 = 64 KB page size supported 31 = 4 KB page size supported Migration Capable H_MIGRATE_DMA Mask. Mask to indicate for which page sizes (as specified in the I/O Page Size Support field), that H_MIGRATE_DMA is supported (for this PE). This is a bit significant field, with the bits defined to align to the bits in the I/O Page Size Support field. R1--2. For the Dynamic DMA Windows (DDW) option: 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 ibm,create-dma-window RTAS call for that PE.

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 starting I/O address of the DMA window, and size. 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 Status of -3 (Parameter Error). Thus, the OS is 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--1. For the Dynamic DMA Windows (DDW) option: RTAS must implement the ibm,create-dma-window call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,create-pe-dma-window Number Inputs 5 Number Outputs 4 Config_addr PE configuration address (Register fields set to 0) PHB_Unit_ID_Hi Represents the most-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr PHB_Unit_ID_Low Represents the least-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr I/O Page Size The value n, where 2 n is the requested I/O page size. Only page sizes obtained from the ibm,query-pe-dma-window RTAS call for the PE are allowed. Values of n from 0-11 are invalid. Requested Window Size The value n, where 2 n is the requested DMA window size. Out Status 990x: Extended delay, where x is a number 0-5 (see text) 0: Success (window created) -1: Hardware Error -2: Busy, try again later -3: Parameter Error LIOBN LIOBN of the DMA window created by this call, if any. If no DMA window was created (that is, if the Status is not 0), then this field is present but not used. I/O Starting Address Hi 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 Status is not 0), then this field is present but not used. I/O Starting Address Low 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 Status is not 0), then this field is present but not used. R1--2. 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 Status is returned.

This RTAS call allows for the removal of PE DMA windows, including those created with the ibm,create-pe-dma-window RTAS call as well as 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 ), or if the last remaining DMA window for the PE is removed and that window is not the default DMA window (see Requirements and ). After removal of a DMA 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 ibm,create-pe-dma-window RTAS call. R1--1. For the Dynamic DMA Windows (DDW) option: RTAS must implement the ibm,remove-dma-window call using the argument call buffer defined by . Parameter Type Name Values In Token Token for ibm,remove-pe-dma-window Number Inputs 1 Number Outputs 1 LIOBN LIOBN of the DMA window to be removed. Out Status 0: Success -1: Hardware Error -3: Parameter error R1--2. For the Dynamic DMA Windows (DDW) option: The caller of the ibm,remove-pe-dma-window RTAS call must assure that 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--3. For the Dynamic DMA Windows (DDW) option: The platform must 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--4. For the Dynamic DMA Windows (DDW) option: In Requirement , the platform must provide the same LIOBN, location, and size as specified in the “ibm,dma-window” property in the OF Device Tree for the PE.

Platforms supporting the DDW option implement extensions described 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 “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 associated with that extension. Thus the property value is designed to grow over time in such a way as to enable earlier client programs to ignore later firmware extensions and later client programs to operate on back level firmware. For this level of compatibility to work, the client code needs to ignore extensions beyond what were defined when the client 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 LoPAR or PAPR Level “ibm,ddw-extensions” list index Value Definition 2.7 2 Token of the i bm,reset-pe-dma-windows RTAS Call 2.7 3 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--1. For compatibility with changing extensions to the Dynamic DMA Windows (DDW) option: The client program must ignore extensions as represented by “ibm,ddw-extensions” value list integers beyond those defined when the client code was written. R1--2. For compatibility with changing extensions to the Dynamic DMA Windows (DDW) option: The client program must be prepared to operate on back level platforms that do not implement all the extensions that were defined when the client code was written, including no extensions at all.

The ibm,reset-dma-windows call resets the TCE table 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--1. For the Dynamic DMA Windows (DDW) option starting with IBM Power Architecture Platform Requirements (PAPR) level 2.7: RTAS must implement the ibm,reset-dma-windows call using the argument call buffer defined by . Parameter Type Name Values In Token Token for Number Inputs 3 Number Outputs 1 config_addr PE configuration address PHB_Unit_ID_HI Represents the most-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr PHB_Unit_ID_Low Represents the least-significant 32-bits of the Unit ID of the PHB that corresponds to the config_addr Out Status 0: Success -1: Hardware Error -2: Busy, Try again later -3: Parameter error R1--2. For the Dynamic DMA Windows (DDW) option starting with IBM Power Architecture Platform Requirements (PAPR) 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 config_addr field contain no valid mappings at the time of the call (that is, that the window(s) is not being used). R1--3. For the Dynamic DMA Windows (DDW) option starting with IBM Power Architecture Platform Requirements (PAPR) 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 “ibm,dma-window” Tree property in the for the PE (same LIOBN, location, and size).