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).