diff --git a/DeviceTree/ch_devtree_system.xml b/DeviceTree/ch_devtree_system.xml index 0d554a6..0ecc79a 100644 --- a/DeviceTree/ch_devtree_system.xml +++ b/DeviceTree/ch_devtree_system.xml @@ -6824,8 +6824,19 @@ For LSIs, the platform shall adhere to the interrupt structure OF representation. - -
+ PAPR may support one of two generations of interrupt controllers with + backward compatible firmware interfaces. The first generation interrupt + controller is represented per + + and its sub sections. + The second generation, External Interrupt Virtualization Engine is + represented either per + + when operated in Legacy Compatibility mode, or per + + and its sub sections when operated in Exploitation mode. + +
PowerPC External Interrupt Controller Nodes This section describes the properties for the PowerPC External @@ -7177,6 +7188,130 @@
+
+ PowerPC External Interrupt Virtualization Engine Nodes + + This section describes the properties for the External Interrupt Virtualization + node. Interrupt controllers are normally packaged inside system chips, however, + they are logically represented in the device tree by the interrupt controller + node. This node reports the logical real addresses through which the client + program can manage the interrupt context for its physical processor thread. + + Event source resources consist of either a single or pair of page addresses + associated with each individual event source that is allocated to the partition. + These addresses do not appear in the device tree; rather the platform provides + the hcall(), H_INT_GET_SOURCE_INFO. + + At a dynamic reconfiguration event, such as adding or removing an IO adapter, + or processor, the associated + “int” + property is added or removed from the partition + configuration and along with it the associated page addresses. + + + + “name” [S] + + Standard + property name that denotes a PowerPC External + Interrupt Controller. + prop-encoded-array: A string, encoded as with + encode-string. + The value of this string shall be + “interrupt-controller”. + + + + + “device_type” [S] + + Standard + property name that indicates an Interrupt + Controller. + prop-encoded-array: A string, encoded as with + encode-string. + The value of this property shall be + “power-ivpe”. + + + + + “reg” [S] + + Standard + property name to define the base logical addresses + and sizes of the registers for managing the interrupt context of a + physical processor thread + + prop-encoded-array: Two + (encode-phys, endcode-int) + pairs. The entries represent the user and OS level views of the + XIVE physical processor thread interrupt management areas respectively + (“TIMA” addresses). The first of the two entries is the base address and + size of the user level view and the second of the two entries is the + base address and size of the OS level view. + + + + + “compatible” [S] + + Standard + property name to define alternate + “name” property values. + + prop-encoded-array: The concatenation, with + encode+, of an arbitrary number of text strings, + each encoded as with + encode-string. + The property value shall include + “ibm,power-ivpe”. + + + + + “ibm,xive_eq-sizes” + + property name: Defines the sizes of event + queues that are supported by for the XIVE option. + + prop-encoded-value: One to N integers, encoded as with + encode-int. + Each integer is expressed as the power of 2 of the event queue size. + For example, a 4K event queue size is represented by the value of 12 + (4K = 212). The integers are arranged in ascending order. + + + + + “ibm,xive-lisn-ranges” + + property name: Defines the LISN ranges assigned + to the client program. + prop-encoded-array: One or more + (LISN, number) pairs, where LISN is a single cell + hexadecimal value between 0x00000000 and 0x7FFFFFFF, and number is an + integer. Each pair represents a contiguous range of LISNs. These LISNs + can be used by the OS for any purpose (eg IPIs). The first range will + contain at least one per possible thread in the partition. + + + + + “interrupt-controller” [S] + + Standard + property name to indicate an interrupt (sub-)tree + root. + prop-encoded-array: <none> The presence of + this property indicates that this node represents an interrupt + controller. + + + + +
+
diff --git a/RTAS/ch_rtas_call_defn.xml b/RTAS/ch_rtas_call_defn.xml index 186c4b3..f5bd0f7 100644 --- a/RTAS/ch_rtas_call_defn.xml +++ b/RTAS/ch_rtas_call_defn.xml @@ -1,7 +1,7 @@ - - + Call Function Definition - + This section specifies the semantics of all the RTAS calls. It specifies the RTAS function name, the contents of its argument call buffer (its token, input parameters, and output values) and semantics. - +
NVRAM Access Functions This architecture requires an area of non-volatile memory (NVRAM) to hold OF options, RTAS information, machine configuration state, OS state, diagnostic logs, etc. The type and size of NVRAM is specified in - the OF device tree. The format of NVRAM is detailed in + the OF device tree. The format of NVRAM is detailed in . - In order to give the OS the ability to access + In order to give the OS the ability to access NVRAM on different platforms that may use different implementations or locations for NVRAM, a layer of abstraction is provided to the OS. The functions in this section provide an interface for reading and writing NVRAM with byte level operations with no boundary requirements. - +
<emphasis>nvram-fetch</emphasis> - The RTAS function + The RTAS function nvram-fetch copies data from a given offset in NVRAM into the user specified buffer. - + - R1-R1--1. - RTAS must implement an + RTAS must implement an nvram-fetch function that returns data from NVRAM - using the argument call buffer defined by + using the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>nvram-fetch</emphasis> @@ -94,7 +94,7 @@ - Token for + Token for nvram-fetch @@ -179,27 +179,27 @@ - + - +
<emphasis>nvram-store</emphasis> - The RTAS function + The RTAS function nvram-store copies data from the user specified buffer to a given offset in NVRAM. - + - R1-R1--1. - RTAS must implement an + RTAS must implement an nvram-store function that stores data in NVRAM using - the argument call buffer defined by + the argument call buffer defined by . - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>nvram-store</emphasis> @@ -235,7 +235,7 @@ - Token for + Token for nvram-store @@ -319,12 +319,12 @@
- + - R1-R1--2. - If the + If the nvram-store operation succeeded, the contents of NVRAM must have been updated to the user specified values. The contents of NVRAM are undefined if the RTAS call failed. @@ -333,46 +333,46 @@ the NVRAM data cached in volatile memory as long as the cache is implemented as a store-through cache and not a store-in cache. That is, changed data is written to NVRAM as soon as possible. Return from the - nvram-store call with a “success” + nvram-store call with a “success” Status is permissible after placing the data into a store-through cache and prior to the actual writing to the NVRAM. - + - R1-R1--3. - The caller of the + The caller of the nvram-store RTAS call must maintain the NVRAM - partitions as specified in + partitions as specified in . - +
- +
- +
Time of Day - The minimum system requirements include a non-volatile + The minimum system requirements include a non-volatile real time clock which maintains the time of day even if power to the machine is removed. Minimum requirements for this clock are described in Requirement - + . - +
Time of Day Inputs/Outputs The OS maintains the clock in UTC. This allows the OS and diagnostics to co-exist with each other and provide uniform handling of time. - + - R1-R1--1. The date and time inputs and outputs to @@ -385,9 +385,9 @@ 29 days in leap years, etc. - + - R1-R1--2. OSs must account for local time, for @@ -395,33 +395,33 @@ seconds. - + - R1-R1--3. RTAS must account for leap years. - +
- +
<emphasis>get-time-of-day</emphasis> - + - R1-R1--1. - RTAS must implement a + RTAS must implement a get-time-of-day call using the argument call buffer - defined by + defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>get-time-of-day</emphasis> @@ -457,7 +457,7 @@ - Token for + Token for get-time-of-day @@ -572,16 +572,16 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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 again. However, software may issue the call again either earlier or later than this. - + - R1-R1--2. RTAS must read the current time and set @@ -589,24 +589,24 @@ - +
- +
<emphasis>set-time-of-day</emphasis> - + - R1-R1--1. - RTAS must implement a + RTAS must implement a set-time-of-day call using the argument call buffer - defined by + defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>set-time-of-day</emphasis> @@ -642,7 +642,7 @@ - Token for + Token for set-time-of-day @@ -757,59 +757,59 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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 again. However, software may issue the call again either earlier or later than this. - + - R1-R1--2. RTAS must set the time of day to the best resolution provided by the platform. - + - R1-R1--3. - RTAS must return a - Status of -3 (Parameter Error) to the + RTAS must return a + Status of -3 (Parameter Error) to the set-time-of-day RTAS call when the specified date is outside the range supported by the platform. Software Implementation Note: The OS maintains the clock in UTC. This allows the OS and diagnostics to co-exist with each other and - provide uniform handling of time. Refer to Requirement + provide uniform handling of time. Refer to Requirement for further details on the time of day clock. - +
- +
<emphasis>set-time-for-power-on</emphasis> Some platforms provide the ability to set a time to cause the - platform power on. The + platform power on. The set-time-for-power-on call provides the interface to the OS for setting this timer. - + - R1-R1--1. - RTAS must implement the + RTAS must implement the set-time-for-power-on call using the argument call - buffer defined by + buffer defined by . - + Argument Call Buffer <emphasis>set-time-for-power-on</emphasis> @@ -847,7 +847,7 @@ - Token for + Token for set-time-for-power-on @@ -963,25 +963,25 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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 again. However, software may issue the call again either earlier or later than this. - + - R1-R1--2. Hardware must support power on times of up to four weeks into the future, at a minimum. - + - R1-R1--3. RTAS must schedule the time for power on @@ -990,7 +990,7 @@ Software Implementation Note: Hardware limitations on the duration of the power-on timer may result in power-on sooner than requested by software. If present in the - /rtas node, the OF property + /rtas node, the OF property “power-on-max-latency” gives in days the maximum power-on duration capability of the hardware. If the property is not present, software should expect the default of a maximum of 28 days. @@ -998,36 +998,36 @@ time. - + - R1-R1--4. If the system is in a powered down state - at the time scheduled by + at the time scheduled by set-time-for-power-on (within the accuracy of the clock), then power must be reapplied and the system must go through its power on sequence. - + - R1-R1--5. - RTAS must return a - Status of -3 (Parameter Error) to the + RTAS must return a + Status of -3 (Parameter Error) to the set-time-for-power-on RTAS call when the specified date is outside the range supported by the platform (such as before current TOD). - +
- +
Error and Event Reporting The error and event reporting RTAS calls are designed to provide an @@ -1043,10 +1043,10 @@ OS. The OS uses the error and event RTAS calls in two distinct ways: - - + + - Periodically, the OS calls + Periodically, the OS calls event-scan to have the system firmware check for any errors or events that have occurred. @@ -1054,10 +1054,10 @@ Whenever the OS receives an interrupt or exception that it - cannot fully process, it calls + cannot fully process, it calls check-exception.. - + The first case covers all errors and events that do not signal their occurrence with an interrupt or exception. The second case covers @@ -1067,21 +1067,21 @@ - R1-R1--1. RTAS must return the event generated by a - particular interrupt or event source by either - check-exception or + particular interrupt or event source by either + check-exception or event-scan, but not both. - + - R1-R1--2. - check-exception and + check-exception and event-scan, on a 64-bit capable platform, must be able to handle platform resources that are accessed using 64-bit addresses when instantiated in 32-bit mode. @@ -1091,18 +1091,18 @@
<emphasis>event-scan</emphasis> - + - R1-R1--1. - RTAS must implement an + RTAS must implement an event-scan call using - the argument call buffer defined by + the argument call buffer defined by . - + Argument Call Buffer <emphasis>event-scan</emphasis> @@ -1140,7 +1140,7 @@ - Token for + Token for event-scan @@ -1225,34 +1225,34 @@
- + - R1-R1--2. The event-scan call must fill in the error log with a - single error log formatted as specified in + single error log formatted as specified in . If necessary, the data placed - into the error log must be truncated to + into the error log must be truncated to length bytes. - + - R1-R1--3. RTAS must only check for errors or events - that are within the classes defined by the + that are within the classes defined by the Event mask. Event mask is a bit mask of error and - event classes. Refer to + event classes. Refer to for the definition of the bit positions. - + - R1-R1--4. If Critical is non-zero, then RTAS must perform only @@ -1260,104 +1260,104 @@ error information is returned. - + - R1-R1--5. The event-scan call must return the first found error or event and clear that error or event so it is only reported once. - + - R1-R1--6. - The OS must continue to call - event-scan while a + The OS must continue to call + event-scan while a Status of “New Error Log returned” is returned. - + - R1-R1--7. - The event-scan call must be made at least + The event-scan call must be made at least “rtas-event-scan-rate” times per minute for each error and event class and - must have the + must have the Critical parameter equal to 0 for this periodic call. - + - R1-R1--8. The platform must not return more than - two error logs during the first sequence of + two error logs during the first sequence of event-scan RTAS calls after boot of an OS image, and must not return more than one error log to that OS image during any - sequence of + sequence of event-scan RTAS calls after the first time a non-zero Status is returned. - + Software Implementation Notes: - - + + In a multiprocessor system, each processor should call - event-scan periodically, not always the same one. The + event-scan periodically, not always the same one. The event-scan function needs to be called a total of “rtas-event-scan-rate” times a minute. - + The maximum size of the error log is specified in the OF device - tree as the + tree as the “rtas-error-log-max” property of the /rtas node. - + This call does not log the error in NVRAM. It returns the error log to the OS. It is the responsibility of the OS to take appropriate action. - + - For best system performance, the requested + For best system performance, the requested “rtas-event-scan-rate” should be as low as possible, and as a goal should not exceed 120 scans per minute. Maximum system performance is obtained when no scans are required. - - + +
- +
<emphasis>check-exception</emphasis> - + - R1-R1--1. - RTAS must implement a + RTAS must implement a check-exception call using the argument call buffer - defined by + defined by . - + Argument Call Buffer <emphasis>check-exception</emphasis> @@ -1395,7 +1395,7 @@ - Token for + Token for check-exception @@ -1427,7 +1427,7 @@ - The vector offset for the exception. See + The vector offset for the exception. See . @@ -1442,7 +1442,7 @@ Information which RTAS may need to determine the cause of the exception, but which may be unavailable to it in hardware - registers. See + registers. See for details. @@ -1494,7 +1494,7 @@ - See Requirement + See Requirement . @@ -1518,21 +1518,21 @@
- + - R1-R1--2. - The OS must provide the value specified in - in the + The OS must provide the value specified in + in the Additional Information parameter in the call to - check-exception, with the + check-exception, with the Number Inputs parameter set to 6. If the value (e.g., SRR1) is too large to fit in this cell, the lower 32-bits must be - provided here, the upper 32-bits provided in the - Extended Information parameter, and the + provided here, the upper 32-bits provided in the + Extended Information parameter, and the Number Inputs parameter set to 7. - + Additional Information Provided to <emphasis>check-exception</emphasis> call @@ -1595,21 +1595,21 @@
- + - R1-R1--3. The check-exception call must fill in the error log with - a single error log formatted as specified in + a single error log formatted as specified in . The data in the error log - must be truncated to + must be truncated to length bytes. - + - R1-R1--4. If Critical is non-zero, then RTAS must perform only @@ -1617,9 +1617,9 @@ error information is returned. - + - R1-R1--5. The check-exception call must return the first found @@ -1627,60 +1627,60 @@ once. - + - R1-R1--6. RTAS must only check for errors or events - that are within the classes defined by the + that are within the classes defined by the Event mask. Event mask is a bit mask of error and - event classes. Refer to + event classes. Refer to for the definition of the bit positions. - + Software Implementation Notes: - - + + - All OS reserved exception handlers should call + All OS reserved exception handlers should call check-exception to process any errors that are unknown to the OS. - + - The + The interrupt number for external device interrupts is - provided in the OF device tree as specified in + provided in the OF device tree as specified in . - + Software, with knowledge of the class of event it seeks, matches the data in the Vector Offset, Additional Information, and Extended Information with the Event Mask such that ambiguity does not result. - - + +
- +
<emphasis>rtas-last-error</emphasis> - + - R1-R1--1. - RTAS must implement an + RTAS must implement an rtas-last-error call using the argument call buffer - defined in + defined in . - + Argument Call Buffer <emphasis>rtas-last-error</emphasis> @@ -1718,7 +1718,7 @@ - Token for + Token for rtas-last-error @@ -1782,80 +1782,80 @@
- + - R1-R1--2. The rtas-last-error call must fill in the error log with - a single error log formatted as specified in + a single error log formatted as specified in . If necessary, the data placed into the error log must be truncated to ‘length” bytes. - + - R1-R1--3. RTAS must only check for hardware errors that occurred during a prior call to some other RTAS function, resulting - in a -1 (Hardware Error) return + in a -1 (Hardware Error) return Status. - + Software Note: This function is intended to provide the OS with more detailed failure information after an RTAS call returns - with a -1 (Hardware Error) + with a -1 (Hardware Error) Status, and should not be called except for this purpose. If - rtas-last-error itself returns a -1 + rtas-last-error itself returns a -1 Status, then it could not create the error log data because of a further error, and the OS should not try to call it again.
- +
Platform Dump Option - + The architectural intent of the Platform Dump option is to allow a mechanism for the platform to communicate a variety of dump data used to debug problems within the platform firmware or hardware. - +
<emphasis>ibm,platform-dump</emphasis> - + This RTAS call is used to transfer dump data from the platform to the OS. It is expected that this routine will have to be called several times to complete the transfer of the diagnostic dump data. It is also anticipated that multiple dumps could be in the process of completion at the same time. Individual dumps are identified by a dump tag passed by - the OS. The OS may interleave calls to + the OS. The OS may interleave calls to ibm,platform-dump with different RTAS calls. Other standard RTAS locking rules apply (for example, only one processor may call RTAS at a time). - The OS only makes the + The OS only makes the ibm,platform-dump RTAS call when an event scan returns an error log with an Event Type of “Dump Notification” as described in Version 6 or later of the RTAS General Extended Error Log Format. - + - R1-R1--1. - For the Platform Dump option: The RTAS function + For the Platform Dump option: The RTAS function ibm,platform-dump must be implemented and must - implement the argument call buffer as defined by + implement the argument call buffer as defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,platform-dump</emphasis> @@ -1891,7 +1891,7 @@ - Token for + Token for ibm,platform-dump @@ -2009,7 +2009,7 @@ Most-significant 32 bits of the Next_Sequence value indicating the portion of the dump to be retrieved on the next - call if needed. (If + call if needed. (If Status is returned as 0, then the dump is complete and there is no next call required. The value of Next_Sequence in this case is undefined.) @@ -2054,22 +2054,22 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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,platform-dump again. However, software may issue - the + the ibm,platform-dump call again either earlier or later than this. - + - R1-R1--2. - For the Platform Dump option: On the first call to + For the Platform Dump option: On the first call to ibm,platform-dump of a platform dump sequence for a given Dump_Tag, the Sequence value must be initialized to zero and on subsequent calls for the same tag, the Dump_Sequence must be set to @@ -2077,25 +2077,25 @@ set to zero to restart the entire dump sequence. - + - R1-R1--3. For the Platform Dump option: The dump tag passed to any call to ibm,platform-dump must be a value specified by the platform - and communicated to the OS by an + and communicated to the OS by an event-scan error log entry. - + - R1-R1--4. - For the Platform Dump option: Once a + For the Platform Dump option: Once a Status of 0 (Dump complete) or -1 (Hardware - error” is returned for the + error” is returned for the ibm,platform-dump call with a particular dump tag, the dump is considered complete from a platform standpoint, but for the “Dump complete” case the OS must signal to the platform that @@ -2103,13 +2103,13 @@ Dump_Tag with the Buffer address set to NULL. - + - R1-R1--5. For the Platform Dump option: If at any time a - partition receives a -9002, Not Authorized, return code for an + partition receives a -9002, Not Authorized, return code for an ibm,platform-dump RTAS, the partition must cease attempting to acquire the dump information it was in process of acquiring and discard any portion already acquired. @@ -2122,53 +2122,53 @@ Management Console (HMC). - + - R1-R1--6. For the Platform Dump option: The contents of dump - information returned through the sequence of calls to + information returned through the sequence of calls to ibm,platform-dump, must follow a dump directory - structure as defined in + structure as defined in . - + - R1-R1--7. For the Platform Dump option: Collectively the dump - data returned from a sequence of + data returned from a sequence of ibm,platform-dump calls for a given Dump_tag must - consist of one dump file directory entry as described in + consist of one dump file directory entry as described in followed by one or more dump - section directory entries as described in + section directory entries as described in followed by a dump data section for each dump section directory entry earlier included. - + Programming Notes: - - + + - As required in + As required in , the OS can determine the - maximum size of a copy of each dump that can be returned by issuing an + maximum size of a copy of each dump that can be returned by issuing an ibm,get-system-parameter for the platform-dump-max-size. In addition, in the case of any change in the value of this parameter, the platform may generate a Platform Event Log entry announcing the change in the maximum size, and specifying the new size in the IO Events Section. This entry, when generated, is then - returned by the + returned by the event-scan RTAS call. - + The Dump_Tag is taken from the Dump Locator Section of the Platform Error/Event Log Format, Version 6 or later. Specifically, @@ -2177,32 +2177,32 @@ quantity. The Dump_Tag_Lo is the Dump ID found in the Dump Locator Section of the Error log entry. - + - If the - ibm,platform-dump RTAS routine returns with the + If the + ibm,platform-dump RTAS routine returns with the Status of 1 (Continue dump), the transfer is proceeding but had to be suspended to maintain the short execution time requirement of RTAS routines or because more data was available than the Buffer could contain. - + The Bytes_Returned value indicates how many bytes of dump data (if any) were returned on a call and OS must be prepared to handle the - case of no bytes returned. When Continue dump + case of no bytes returned. When Continue dump Status (1) is returned, this indicates that there is more dump data available then was returned in the buffer. A subsequent call with the same Dump_tag and the Sequence value being set to the Next_Sequence returned from the previous call returns additional dump data. - + - When a dump has been successfully transmitted, the + When a dump has been successfully transmitted, the Status of 0 (Dump complete) is returned. If there is a hardware error preventing a dump from being successfully transmitted, - as + as Status of -1 (Hardware error) is returned. In either case, the Dump sequence is completed. It should be noted that the final Next_Sequence value returned is undefined. After the sequence is @@ -2213,40 +2213,40 @@ platform that the OS has completed processing of the dump and will not attempt to restart the sequence. - + If the platform used system memory to hold dump data, the platform at this point is permitted to free the associated logical memory - blocks (LMBs) reserved for the dump. Successful return from the + blocks (LMBs) reserved for the dump. Successful return from the ibm,platform-dump RTAS call with a NULL buffer pointer indicates to the OS that one or more logical memory blocks (LMBs) may now be acquired by the OS. A get-sensor-state RTAS call for these LMBs returns with a state of “DR entity available for recovery - (4)” after the successful return from this + (4)” after the successful return from this ibm,platform-dump RTAS call. - + If a platform does not receive the NULL buffer pointer call dump for a given Dump_Tag but subsequently boots the partition, the platform may report the presence of the dump again on an e vent-scan after the boot. - - + +
- +
Platform Dump Directory Structure - - The entire dump contents returned over a sequence of + + The entire dump contents returned over a sequence of ibm,platform-dump RTAS calls for a given Dump_Tag - follows a directory/data structure as illustrated in - and + follows a directory/data structure as illustrated in + and where a dump consists of one File Directory Entry, one or more Section Directory Entries and one data section for each Section Directory entry. - + Platform Dump File Directory Entry Format @@ -2332,7 +2332,7 @@ 4 Bytes - See + See . @@ -2392,7 +2392,7 @@
- + Dump Section Directory Entry Format @@ -2468,7 +2468,7 @@ Unsigned integer - See programming note after + See programming note after . @@ -2494,7 +2494,7 @@ 4 Bytes - See + See . @@ -2567,9 +2567,9 @@ The two previous tables refer to a set of flags used to describe information related to a dump section. The options are stored in a single 32 bit value which is the bit-wise OR'ing of each option value defined in - + . - +
Dump File Format Directory Options @@ -2655,16 +2655,16 @@ Software Implementation Notes: - - + + - Platforms supporting the + Platforms supporting the ibm,platform-dump call may have several unique dump types. All dumps of the same type on a partition have the same “prefix” to the name of the dump file as indicated in the dump file directory entry in an error log. - + The priority in the priority field of the section directory entries allow an application transmitting a dump to a remote support @@ -2676,26 +2676,26 @@ Format Directory Options flag set to a 1 if the section data cannot be transmitted. - - + + - +
PCI Configuration Space - Device drivers and system software need access to + Device drivers and system software need access to PCI - configuration space. + configuration space. section on "Address Map" defines system address spaces for PCI memory and PCI I/O spaces. It does not define an address space for PCI configuration. Different PCI bridges may implement the mechanisms for accessing PCI configuration space in different ways. The RTAS calls in this section provide an abstract way of reading and writing PCI configuration spaces. - The PCI access functions take a + The PCI access functions take a config_addr input parameter which is similar to the Type 1 PCI configuration space address. For conventional PCI and PCI-X Mode 1, this address is a 24-bit quantity composed of bus, device, @@ -2704,22 +2704,22 @@ and 256 bytes of register space per function. PCI-X Mode 2 and PCI Express define an extended configuration space with an additional 4-bit quantity which specifies an extended register number allowing for 4096 - bytes of register space per function. Refer to the - or the + bytes of register space per function. Refer to the + or the for more details. The config_addr for an IOA is derived from the OF device tree, and is defined - in + in . - The - ibm,read-pci-config and + The + ibm,read-pci-config and ibm,write-pci-config RTAS calls allow for the specification of the PHB Bus Unit ID, and therefore allow for up to 256 - unique + unique config_addr bus numbers per PHB. Note that for each pci connector, there may be multiple PCI bus numbers, because plug-in PCI cards may contain PCI to PCI bridges, which create other PCI buses. - The + The PCI Local Bus Specification requires that unimplemented or reserved register space read as 0’s, and that reads of the Vendor ID register of IOAs or functions which aren’t @@ -2731,21 +2731,21 @@ - R1-R1--1. For the RTAS PCI - configuration space and EEH functions where the parameter - config_addr is requested as input, the + configuration space and EEH functions where the parameter + config_addr is requested as input, the config_addr parameter must be as specified by the hi cell of the physical address in Open Firmware Working Group proposal - number 516 Ver 1.8 (see + number 516 Ver 1.8 (see ), with the upper register address bits added for PCI-X Mode 2 and PCI Express, in order to access past the first 256 bytes of configuration space.
- Definition + <title>Definition <emphasis>Config_addr</emphasis> @@ -2774,7 +2774,7 @@ otherwise 0. Set to 0 when the PCI extended configuration space is not available, due to lack of support somewhere from the PHB to the IOA. When a value of this field can be something other - than 0, the + than 0, the “ibm,pci-config-space-type” property will exist in the IOA's node with a value indicating that the @@ -2827,21 +2827,21 @@
- + - R1-R1--2. All RTAS PCI Read/Write functions must follow the appropriate PCI specification. - + - R1-R1--3. - RTAS must follow the rules of + RTAS must follow the rules of when accessing PCI configuration space. @@ -2852,11 +2852,11 @@ Software Implementation Notes: - + Since PCI Configuration space is defined to be Little-Endian, - RTAS accesses this area using the byte-reversed forms of the - Load and + RTAS accesses this area using the byte-reversed forms of the + Load and Store instructions. In this fashion, the values passed are defined Big-Endian. @@ -2864,30 +2864,30 @@ Prior to accessing the extended configuration address space of PCI-X Mode 2 and PCI Express devices, an IOA device driver is responsible - for checking if the + for checking if the “ibm,pci-config-space-type” property (see ) of the IOA's node exists and is set to a non-zero value. - +
<emphasis>ibm,read-pci-config</emphasis> - + - R1-R1--1. For Platforms which may have greater than 256 PCI - Buses: RTAS must implement an + Buses: RTAS must implement an ibm,read-pci-config call using - the argument call buffer defined by + the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,read-pci-config</emphasis> @@ -2923,7 +2923,7 @@ - Token for + Token for ibm,read-pci-config @@ -2965,7 +2965,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 @@ -2977,7 +2977,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 @@ -3023,71 +3023,71 @@
- + - R1-R1--2. - The + The ibm,read-pci-config call must return the value from the configuration register which is at the location specified by the PHB - Unit ID and + Unit ID and config_addr in PCI configuration space. - + - R1-R1--3. The ibm,read-pci-config call must perform a 1-byte, - 2-byte, or 4-byte configuration space read depending on the value of the + 2-byte, or 4-byte configuration space read depending on the value of the size input argument. - + - R1-R1--4. - The config_addr must be aligned to a 2-byte boundary if - size is 2 and to a 4-byte boundary if + The config_addr must be aligned to a 2-byte boundary if + size is 2 and to a 4-byte boundary if size is 4. - + - R1-R1--5. The ibm,read-pci-config call of IOAs or functions which are not present or which - are not available to the caller must return - Success with all ones as the output + are not available to the caller must return + Success with all ones as the output value. - +
- +
<emphasis>ibm,write-pci-config</emphasis> - + - R1-R1--1. For Platforms which may have greater than 256 PCI - Buses: RTAS must implement an + Buses: RTAS must implement an ibm,write-pci-config call - using the argument call buffer defined by + using the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,write-pci-config</emphasis> @@ -3123,7 +3123,7 @@ - Token for + Token for ibm,write-pci-config @@ -3165,7 +3165,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 @@ -3177,7 +3177,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 @@ -3224,81 +3224,81 @@
- + - R1-R1--2. The ibm,write-pci-config call must store the value to the configuration register which is at the location specified by the PHB Unit - ID and + ID and config_addr in PCI configuration space. - + - R1-R1--3. The ibm,write-pci-config call must perform a 1-byte, - 2-byte, or 4-byte configuration space write depending on the value of the + 2-byte, or 4-byte configuration space write depending on the value of the size input argument. - + - R1-R1--4. - The config_addr must be aligned to a 2-byte boundary if - size is 2 and to a 4-byte boundary if + The config_addr must be aligned to a 2-byte boundary if + size is 2 and to a 4-byte boundary if size is 4. - + - R1-R1--5. The ibm,write-pci-config call of IOAs or functions which are not present or which - are not available to the caller must be ignored and a + are not available to the caller must be ignored and a Status of 0 (Success) must be returned. - + - R1-R1--6. - For the LPAR option: The + For the LPAR option: The Status of -3 (Parameter or device enablement error) must be returned if all the following are true: - - + + - The OS attempts an + The OS attempts an ibm,write-pci-config to enable Memory or I/O for an - IOA, without first calling + IOA, without first calling ibm,set-eeh-option to enable EEH for the IOA - + Enabling the IOA could expose other partitions to errors from the partition which is enabling the IOA - + The hypervisor is enforcing EEH mode - - + + - Platform Implementation Note: In Requirement + Platform Implementation Note: In Requirement - , + , cross-partition errors could be caused due to error domains which are shared between the partitions. However, it is acceptable to share error domains when the IOA and its @@ -3309,9 +3309,9 @@
- +
- +
Operator Interfaces and Platform Control The RTAS operator interface and platform control functions provide @@ -3327,14 +3327,14 @@ RTAS to either return an error, or to virtualize the service in some way and return “Operation Succeeded.” Software Implementation Notes: - - + + For example, a keyswitch could be virtualized by storing a keyswitch value in NVRAM and by providing a user interface to modify this value. The RTAS - call - get-sensor-state on the + call + get-sensor-state on the keyswitch returns the value stored in NVRAM. @@ -3343,17 +3343,17 @@ underlying devices by the OS, for example, during boot time, or only after the OS has finished using the devices, for example, during a crash, then the OS can avoid mutual exclusion and sharing concerns. Otherwise, - synchronization per + synchronization per , must be performed. - +
Op Panel Display - + - R1-R1--1. Platform Implementation: @@ -3362,16 +3362,16 @@ display-character RTAS call. Implementation Note: The operator display mechanism - in Requirement + in Requirement may be a physical alphanumeric display with a special purpose LCD device marked “used by RTAS”, or it may be some other virtualized display which is accessible through some method not defined by this architecture. - + - R1-R1--2. Platform Implementation: Servers which provide @@ -3380,12 +3380,12 @@ - + Software Implementation Notes: - - + + There are currently four uses for the op panel display. The first is for display of an error code, if needed, from the @@ -3402,39 +3402,39 @@ three, of 2 to 32 characters. The fourth is a crash code from the OS which is 12 characters indicating cause and dump status. - + The RTAS set-indicator call with token #6 specifies 4 hex - digits. The + digits. The display-character call requires a minimum display size of one line of 4 characters, but a larger display may be made known - to the OS using the “ibm,” extension properties defined in + to the OS using the “ibm,” extension properties defined in . When the message to be displayed is larger than the OS believes the display to be, the OS should perform appropriate truncation, scrolling, or otherwise meaningfully display the message using the platform’s display resource. - + Some servers implement a display larger than the default. For - these servers, the + these servers, the “ibm,display-line-length” property and - the + the “ibm,display-number-of-lines” property are set appropriately. - + If the OS assumes the default display, the 2X16 display still works. It appears to be working in the bottom line and scrolling through the top line as long as only CR and LF are issued for control. The OF device tree properties indicate what is supported. - - + +
- +
Service Processor A service processor is not a platform requirement. Larger servers @@ -3455,7 +3455,7 @@ of RTAS functions which use the service processor, care should be taken to avoid interlocks with the service processor which could significantly impair performance. - +
Surveillance Platforms which include a service processor have the needed @@ -3467,12 +3467,12 @@ notification can be sent to a service center or to a customer administrator, as determined by the customer setup of configuration parameters. The firmware provides notification to the OS by reporting - exceptions through + exceptions through event-scan. The service processor can provide dial-out notification if the OS stops, or if a boot process fails. In the implementation of surveillance, the service processor monitors the OS by tracking the issuance of heartbeats generated by calls - to the + to the event-scan RTAS service. If a service processor time-out occurs prior to receiving another heartbeat, an action based on user defined call out policy occurs. This action could be to reboot, call @@ -3482,53 +3482,53 @@ changed from a service processor menu or from software. The platform can be configured such that surveillance is either enabled or disabled immediately after boot. After boot, temporary changes to the surveillance - state can be made by issuing a - set-indicator call to indicator 9000 (see + state can be made by issuing a + set-indicator call to indicator 9000 (see ). The following system parameters define the default behavior of - surveillance mode (see also, + surveillance mode (see also, for more information about these parameters and for their default values). - - + + - The + The sp-sen system parameter defines whether the default state of surveillance by the service processor is enabled (=on) or disabled (=off). - + - The + The sp-sti system parameter defines the period of time (1-255 minutes) that the service processor should wait between heartbeats - from + from event-scan. If the time-out period expires without the service processor receiving another heartbeat, the service processor initiates recovery and reporting actions as defined by the user. - + - The + The sp-sdel system parameter defines the period of time (1-120 minutes) that the service processor should wait before starting surveillance after control passes to the OS. This value is set to allow enough time for the OS to boot and initialize to the point where it can - start calling + start calling event-scan on a regular periodic basis. - - + + Architecture Note: Surveillance times out if the - time of the parameter, - sp-sdel, plus the time of the parameter, + time of the parameter, + sp-sdel, plus the time of the parameter, sp-sti, passes prior to receiving the first - heartbeat. In effect, the first + heartbeat. In effect, the first event-scan can be considered the signal for boot complete. The platform may perform surveillance on the service processor - using + using event-scan to trigger checking as well as for reporting any errors found. Software Implementation Note: @@ -3537,74 +3537,74 @@ hung and the OS is still functioning, it is the responsibility of the OS to detect and not the surveillance discussed here. OF Implementation Note: - The OS is expected to call the + The OS is expected to call the event-scan RTAS service (with the internal-errors - mask bit on) at the rate defined by the property + mask bit on) at the rate defined by the property “rtas-event-scan-rate” in the OF device - tree. If an + tree. If an “rtas-event-scan-rate” of zero (0) is placed in the OF device tree and surveillance is initialized as ‘active’, a surveillance time-out occurs after the time-out - period since the heartbeats are triggered by the + period since the heartbeats are triggered by the event-scan call. If there is reason to operate with the rate = 0, the default state of surveillance ( sp-sen parameter in NVRAM) should be disabled, and the surveillance sensor and indicator should not be placed in the OF device tree. - + - R1-R1--1. Platform Implementation: The default surveillance policy must be defined by the - sp-sen, - sp-sti and + sp-sen, + sp-sti and sp-sdel system parameters, as set by the service processor or by software. - + - R1-R1--2. Platform Implementation: Heartbeats to the service processor must only be sent as the result of a call to the event-scan RTAS service with the internal-errors bit (bit 0) set to 1 in the call - buffer + buffer Event Mask parameter. - + - R1-R1--3. Platform Implementation: In platforms which implement - surveillance, the + surveillance, the event-scan RTAS service may be called more than once per minute, but the heartbeat to the service processor must be sent at the rate of at least once per minute. - + - R1-R1--4. Platform Implementation: In platforms which implement - surveillance, the + surveillance, the ibm,os-term RTAS call must be implemented. - + - Software Note: Requirement + Software Note: Requirement provides a mechanism for the OS to release control of the platform without being aware of the state of surveillance. With the definition of a default platform state for @@ -3613,129 +3613,129 @@ surveillance during normal shutdown (a shutdown not including immediate reboot).
- +
Surveillance on SMP Systems Each running processor in an SMP system should be covered by surveillance. The following requirements assure this coverage. - + - R1-R1--1. Each processor which is running, that is, not stopped by the stop-self RTAS call or not stopped due to BIST testing at bring-up, must issue the event-scan RTAS call. The rate of - issue is the + issue is the “rtas-event-scan-rate” times per minute divided by the number of processors. This is the minimum rate. - + - R1-R1--2. The system must allow for all processors to cycle through their event-scan calls. The timeout period - for a surveillance event, which is + for a surveillance event, which is sp-sti, must be greater than n time t, where n is - the number of processors and t is the + the number of processors and t is the “rtas-event-scan-rate”. - + - R1-R1--3. The surveillance event must be signaled - if after the surveillance interval, + if after the surveillance interval, sp-sti, one or more processors has not issued an event-scan call. - + Implementation Note: Care is required in the - assignment of the surveillance interval and the + assignment of the surveillance interval and the “rtas-event-scan-rate” such that a surveillance event is not signaled prematurely. The default values are not meant for a system with a large number of processors.
- +
<emphasis>display-character</emphasis> - The + The display-character function allows the display of both alphabetic and numeric information. The display for this function requires at least one line of four (4) characters. Also specified are the control characters carriage-return (CR) (0x0D) and line-feed (LF) (0x0A). - The following OF properties are defined in + The following OF properties are defined in : - - + + “ibm,display-line-length” - + “ibm,display-number-of-lines” - + “ibm,display-truncation-length” - + “ibm,form-feed” - - + + - R1-R1--1. - If + If display-character is implemented on a platform, the - property - “ibm,display-line-length” in the + property + “ibm,display-line-length” in the /rtas node must be provided if greater than the required minimum default of 4 characters. - + - R1-R1--2. - If + If display-character is implemented on a platform, the - property + property “ibm,display-number-of-lines” in the /rtas node must be provided if greater than the required minimum default of 1 line. - + - R1-R1--3. - If the + If the “ibm,display-number-of-lines” is greater than one, the platform must support form-feed (FF) (0x0C). - + - R1-R1--4. If form-feed is implemented, it must @@ -3743,65 +3743,65 @@ 1. - + - R1-R1--5. - The platform must include the property + The platform must include the property “ibm,form-feed” in the /rtas node. - + - R1-R1--6. - For the + For the display-character RTAS call, when the truncation - length as specified in the + length as specified in the “ibm,display-truncation-length” property, when it exists, is less than the length of the line being displayed on that particular line, then the firmware must truncate the requested line - to be displayed to the length specified in the + to be displayed to the length specified in the “ibm,display-truncation-length” property for that line. - + - R1-R1--7. - For the + For the display-character RTAS call, when the truncation - length as specified in the + length as specified in the “ibm,display-truncation-length” property, when it exists, is greater than the length specified of the line as - specified in + specified in “ibm,display-line-length” then the platform must provide a platform-dependent method of displaying the line to the user. - + - R1-R1--8. For platforms that use converged location - codes, the platform must provide scrolling for the + codes, the platform must provide scrolling for the display-character RTAS call, on the second line of - the display, and must provide the + the display, and must provide the “ibm,display-truncation-length” property and specify a truncation length of no less than 80 characters for that line. Platform and Software Implementation Note: In - implementing Requirements - and + implementing Requirements + and , it is permissible to have a separate buffer for any of the lines of the display and not display that line until a button is pressed. @@ -3813,27 +3813,27 @@ vendor specific. - + - R1-R1--9. - RTAS must implement a + RTAS must implement a display-character call using - the argument call buffer defined by + the argument call buffer defined by to place a character on the output device. - + - R1-R1--10. - The OS must serialize all calls to - display-character with any other use of the + The OS must serialize all calls to + display-character with any other use of the rtas-display-device. - + Argument Call Buffer <emphasis>display-character</emphasis> @@ -3871,7 +3871,7 @@ - Token for + Token for display-character @@ -3925,20 +3925,20 @@
- + - R1-R1--11. If a physical - output device is used for the output of the RTAS + output device is used for the output of the RTAS display-character call, then it must have at least one line and 4 characters. - + - R1-R1--12. Certain ASCII control characters must @@ -3949,16 +3949,16 @@ and scroll old data off the top. - + - R1-R1--13. The ASCII characters which must be - displayed are generally those coded from 0x20 to 0x7E as shown in + displayed are generally those coded from 0x20 to 0x7E as shown in . SP indicates a space and ND is not defined - + Display ASCII Characters @@ -4658,41 +4658,41 @@ and the tilde, ~(0x7E). - + - R1-R1--14. RTAS must not - output characters to the + output characters to the rtas-display-device except for explicit calls from - the OS to the + the OS to the display-character function except for the following conditions. - - + + - The rtas-display-device is marked + The rtas-display-device is marked “used-by-rtas”. - + - The RTAS call is + The RTAS call is power-off, ibm,power-off-ups, set-power-level (0,0), or system-reboot. - + - - + + Software Implementation Notes: - - + + RTAS should try to produce output to the user. This could be to the system console, to an attached terminal, or to some other device. It @@ -4700,41 +4700,41 @@ also implement this call by storing the messages in a buffer in NVRAM so the user could determine the reason for a crash upon reboot. - + - This call modifies the registers associated with the + This call modifies the registers associated with the rtas-display-device. The OS may also access this - device, being aware that calls to + device, being aware that calls to display-character change the state of the device. - - + + - +
<emphasis>set-indicator</emphasis> - The RTAS + The RTAS set-indicator function provides the OS with an abstraction for controlling various lights, indicators, and other resources on a platform. If multiple indicators of a given type are provided by the platform, this function permits addressing them individually. - + - R1-R1--1. - RTAS must implement a + RTAS must implement a set-indicator call which sets the value of the - indicator of type - Indicator and index + indicator of type + Indicator and index Indicator-index using the argument call buffer - defined by - and indicator types defined by + defined by + and indicator types defined by . - +
Argument Call Buffer <emphasis>set-indicator</emphasis> @@ -4772,7 +4772,7 @@ - Token for + Token for set-indicator @@ -4850,65 +4850,65 @@
- + - R1-R1--2. - For indicators in the + For indicators in the “rtas-indicators” property, the indices for indicators must start at zero (0) and increment sequentially up to the maximum index; that is, all of the integers and only those integers from 0 to the maximum index are valid. Architecture Note: Indicator indices that are - obtained via the + obtained via the ibm,get-indices RTAS call are not necessarily - contiguous (that is, any of the indices between 0 and the + contiguous (that is, any of the indices between 0 and the maxindex, inclusive, may be missing). - + - R1-R1--3. - Of the indicator types defined by + Of the indicator types defined by , RTAS must implement at least Tone Frequency and Tone Volume. - + - R1-R1--4. - The + The set-indicator RTAS call must not return a busy - indication (-2 or 990x) for any indicator in + indication (-2 or 990x) for any indicator in which is marked with a “yes” in the “Fast?” column of that table. - + - R1-R1--5. The platform may, but is not required to, turn off a tone automatically after 5 minutes or more duration (that is, automatically set the Tone Volume to zero), and therefore a user of the - Tone must call + Tone must call set-indicator Tone Volume with a volume value of non-zero, if a tone is to be sustained longer than 5 minutes, and if the platform is going to automatically terminate the tone, the platform must - reset its automatic turn-off timer when it receives a + reset its automatic turn-off timer when it receives a set-indicator call for the Tone Volume with a non-zero tone volume value. - + Defined Indicators @@ -4958,10 +4958,10 @@ Values in the “<vendor>” column are used to replace the “ - <vendor>” field of the + <vendor>” field of the “<vendor>,indicator-<token>” property, when that property is - presented. See Requirement + presented. See Requirement . @@ -4992,7 +4992,7 @@ yes - When tone is required. See Requirement + When tone is required. See Requirement . @@ -5022,7 +5022,7 @@ yes - When tone is required. See Requirement + When tone is required. See Requirement . @@ -5169,7 +5169,7 @@ Isolate refers to the DR action to logically disconnect from the platform and/or OS (for example, for PCI, isolate from - the bus and from the OS). See + the bus and from the OS). See for more details. @@ -5205,8 +5205,8 @@ combines Power/Active indicator and Identify/Action indications or just an Identify/Action indicator. Identify and Action may map to the same visual state (for example, the same blink - rate). See - and + rate). See + and for more information. @@ -5239,7 +5239,7 @@ Allows an OS image to assign (usable, exchange, or recover) resources from the firmware or, release resources from - the OS to the firmware. See + the OS to the firmware. See for more details. @@ -5288,7 +5288,7 @@ yes - See Requirement + See Requirement . @@ -5320,7 +5320,7 @@ Yes - See + See . @@ -5334,8 +5334,8 @@ firmware and/or diagnostics detected a fault (failure) in the system or a partition requires operator intervention for another reason. The Error Log indicator is located only on the - Primary Enclosure. See - and + Primary Enclosure. See + and for more information. @@ -5359,7 +5359,7 @@ Yes - See + See . @@ -5376,8 +5376,8 @@ indicator that is both a 9002 and 9007 indicator, nor does it protect against the use of multiple 9007 indicators simultaneously or multiple uses of the same 9007 indicator - simultaneously. See - and + simultaneously. See + and for more information. @@ -5467,36 +5467,36 @@
- +
Indicators - +
Indicator 9000 Surveillance An indicator is defined with the token value 9000 to allow temporary modification of the state of the surveillance function (further - described in + described in ). - To enable monitoring of heartbeats from the + To enable monitoring of heartbeats from the event-scan RTAS call, the surveillance indicator is set with a value of 1 to 255, indicating the number of minutes for the surveillance time-out value. If monitoring is already enabled, the time-out value can be modified by setting this indicator. To disable monitoring, the surveillance indicator should be set to a value of zero - (0). The + (0). The set-indicator call is used to modify the state of surveillance (overriding the default system parameter values) only for the current session. The surveillance state returns to the default values when the system is rebooted. The default surveillance configuration may be modified by changing the system parameters. For more information on these parameters, refer to - + . - + - R1-R1--1. Platforms with the surveillance @@ -5507,11 +5507,11 @@ - + Firmware Implementation Note: The requirement above - results in the creation of the properties - “ibm,indicator-9000” and + results in the creation of the properties + “ibm,indicator-9000” and “ibm,sensor-9000” in the /rtas node. @@ -5519,7 +5519,7 @@ service processor takes in the case of a timeout is determined by the configuration setup policy in the system parameters.
- +
Indicator 9005 Global Interrupt Queue Control The 9005 indicator controls the global interrupt server queue logic @@ -5527,28 +5527,28 @@ call (Available Processor Mask (APM) for the PowerPC interrupt presentation controller). This is used when bringing a processor online and taking a processor offline. - + - R1-R1--1. Platforms that allow processors to be brought online or be taken offline dynamically must implement the global interrupt queue control indicator with a value - of 9005 as specified in + of 9005 as specified in . - + - R1-R1--2. The index value for global interrupt queue control indicator (9005) must be (2 - ibm,interruptserver#-size) - 1 - the + ibm,interrupt-server#-size) - 1 - the gserver# of the global server to be controlled as given in the @@ -5556,46 +5556,46 @@ - +
- +
<emphasis>get-sensor-state</emphasis> - The RTAS call + The RTAS call get-sensor-state is used by the OS to read the current state of various sensors on any Platform. If multiple sensors of a given type are provided by the platform, this function permits addressing them individually. - + - R1-R1--1. - RTAS must implement a + RTAS must implement a get-sensor-state call which - reads the value of the sensor of type - Sensor which has index + reads the value of the sensor of type + Sensor which has index Sensor-index using the argument call buffer defined - by + by and the sensor types defined by - + . - + - R1-R1--2. If a platform tests sensor values against - limits, then RTAS must return the result of these tests using the + limits, then RTAS must return the result of these tests using the Status output parameter. - + <emphasis>get-sensor-state</emphasis> Argument Call Buffer @@ -5710,7 +5710,7 @@ - Current value as defined in the Defined Values column of + Current value as defined in the Defined Values column of . @@ -5718,101 +5718,101 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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 get-sensor-state again. However, software may issue - the + the get-sensor-state call again either earlier or later than this. - + - R1-R1--3. - For sensors in the + For sensors in the “rtas-sensors” property, the indices for sensors must start at zero (0) and increment sequentially up to the maximum index; that is, all of the integers and only those integers from 0 to the maximum index are valid. Architecture Note: Sensor indices that are obtained - via the + via the ibm,get-indices RTAS call are not necessarily - contiguous (that is, any of the indices between 0 and the + contiguous (that is, any of the indices between 0 and the maxindex, inclusive, may be missing). - + - R1-R1--4. The get-sensor RTAS call must not return a busy - indication (-2 or 990x) for any indicator in + indication (-2 or 990x) for any indicator in which is marked with a “yes” in the “Fast?” column of that table. - + Hardware Implementation Note: Some platforms may compare the value of environmental sensors (such as the Battery Voltage or Thermal Sensor) to some limits. When the value of the sensor meets or exceeds a limit, the platform may take some action. RTAS makes the OS - aware of the relationship of the sensor values to the limit by using the + aware of the relationship of the sensor values to the limit by using the Status code to return this information. Software and Hardware Implementation Notes: The meaning of these limits is as follows: - - + + Critical High - The sensor value is greater than or equal to this - limit. The platform may take some action and may initiate an EPOW (see + limit. The platform may take some action and may initiate an EPOW (see ). The OS may take some action to correct this situation or to perform an orderly shutdown. - + Warning High - The sensor value is greater than or equal to this limit, but less than the critical high limit. The platform may initiate a warning EPOW. The OS may take some action to bring this reading back into the normal range. - + Normal - RTAS is aware of the limits and the value is within these operating limits. - + Warning Low - The sensor value is less than or equal to this limit, but greater than the critical low limit. The platform may initiate a warning EPOW. The OS may take some action to bring this reading back into the normal range. - + Critical Low - The sensor value is less than or equal to this limit. The platform may take some action and may initiate an EPOW. The OS may take some action to correct this situation or to perform an orderly shutdown. - + Where: - + A ‘critical’ state is defined as a condition where the sensor value of the measured item indicates that it is outside the allowable operating parameters of the system, and that a failure is imminent unless some immediate action is taken. - + A ‘warning’ state is defined as a condition where the sensor value of the measured item indicates that it is outside the @@ -5821,14 +5821,14 @@ system software or an operator may want to take some action to bring the parameter back into the normal range. - - + + Platform Implementation Note: The existence of this sensor state reporting capability should not be construed as a requirement to have any limits on sensors or to always have all four limits. - + Defined Sensors @@ -5872,9 +5872,9 @@ Values in the “<vendor>” column are used to replace the “ - <vendor>” field of the + <vendor>” field of the “<vendor>,sensor-<token>” - property, when that property is presented. See Requirement + property, when that property is presented. See Requirement . @@ -6259,8 +6259,8 @@ Used in Dynamic Reconfiguration operations to determine if connector is available and whether the user performed a - particular DR operation correctly. See - and + particular DR operation correctly. See + and . @@ -6302,7 +6302,7 @@ yes - See Requirement + See Requirement . @@ -6330,7 +6330,7 @@ Yes - See + See . @@ -6358,7 +6358,7 @@ Yes - See + See . @@ -6447,19 +6447,19 @@
- +
Sensors - The current state of surveillance, as described in - , is queried with a call to + The current state of surveillance, as described in + , is queried with a call to get-sensor-state with a token value of 9000. Fan speed is queried with the token value of 9001 and an index specifying the desired fan. Similarly, voltage is sensed with a token value of 9002 and an index specifying the desired voltage source. - + - R1-R1--1. Platforms which implement the @@ -6469,9 +6469,9 @@ session. - + - R1-R1--2. Platforms with software visible fan @@ -6480,9 +6480,9 @@ (RPM). - + - R1-R1--3. Platforms with software visible voltage @@ -6491,23 +6491,23 @@ - - Hardware Implementation Note: + + Hardware Implementation Note: The notion of a delay, due to the sensor data acquisition time, may make it desirable to cache sensor data to avoid interlocking with the service processor. Software Implementation Note: Software should not assume that sensor data returned is a real time reading. - +
Example Implementation of Sensors An example implementation of a platform with a service processor and four fans and four voltage sensors is represented by the paired integers ( - token maxindex) in the OF device tree as shown in + token maxindex) in the OF device tree as shown in . - + Example - Contents of <emphasis role="bold"><literal>“rtas-sensors”</literal></emphasis> property @@ -6570,9 +6570,9 @@
- This requires sensors such as those shown in + This requires sensors such as those shown in . - + Example - Sensor Definitions @@ -6735,37 +6735,37 @@
In addition, the properties - “ibm,sensor-9000”, - “ibm,sensor-9001” and + “ibm,sensor-9000”, + “ibm,sensor-9001” and “ibm,sensor-9002” in the /rtas node that each contain an array of strings. Each entry in the array contains the location code for the matching - sensor. For example, the first entry of + sensor. For example, the first entry of “ibm,sensor-9001” contains the location - code for fan#1. Location codes are shown in + code for fan#1. Location codes are shown in . Of course, since it is an - abstracted sensor, the entry for + abstracted sensor, the entry for “ibm,sensor-9000” is NULL.
- +
Power Supply Sensors - + - R1-R1--1. Platforms with multiple software visible power supply sensors must implement them as defined RTAS sensors - with the token value of 9004, which returns the values defined in + with the token value of 9004, which returns the values defined in . - - - + + +
Power Supply Sensor Values @@ -6820,57 +6820,57 @@
- For static 9004 sensors, the maxindex in the + For static 9004 sensors, the maxindex in the “rtas-sensors” property for the token 9004 indicates the number of power supplies supported by the platform. In - this case, the property + this case, the property “ibm,sensor-9004” in the /rtas node contains the location code for each index. For dynamic 9004 sensors, the platform provides the information about the 9004 indicators as it would for other dynamic sensors. That is, - the platform does not provide the + the platform does not provide the “ibm,sensor-9004” property and instead - provides the 9004 location code information through the - ibm,get-indices RTAS call, and if the + provides the 9004 location code information through the + ibm,get-indices RTAS call, and if the ibm,get-indices RTAS call returns an index of all-1's - for a 9004 indicator, then the + for a 9004 indicator, then the ibm,get-dynamic-sensor-state RTAS call is used to get - the sensor state, instead of the + the sensor state, instead of the get-sensor RTAS call.
- +
Environmental Sensors - + - R1-R1--1. Platforms which want to allow an application to analyze their environmental sensors must provide the - property + property “ibm,environmental-sensors” in the - /rtas node (see + /rtas node (see ). - + The values for this property is a list of integers that are the token values (token) for the defined environmental sensors and the number of sensors (maxindex) for that token which are implemented on the platform. Architecture Note: - When a sensor is in the + When a sensor is in the “ibm,environmental-sensors” property and - when the sensor token indices are obtained via the + when the sensor token indices are obtained via the ibm,get-indices RTAS call, the indices may not be contiguous for that sensor token (that is, any of the indices between 0 and the maxindex, inclusive, may be missing).
- +
Sensor 9005 Global Interrupt Queue Control State @@ -6879,65 +6879,73 @@ processor making the call (Available Processor Mask (APM) for the PowerPC interrupt presentation controller). This is used when varying the processor on and off line. - + - R1-R1--1. Platforms that allow processors to be brought online or be taken offline dynamically must implement the global - interrupt queue control sensor with a value of 9005 as specified in + interrupt queue control sensor with a value of 9005 as specified in . - + - R1-R1--2. - RThe index value for global interrupt - queue control state sensor (9005) must be - (2 - ibm,interrupt-server#-size) - 1- the gserver# of the - global queue to be sensed as given in the - - “ibm,ppc-interrupt-gserver#s” property. + + + For legacy compatibility mode, the index value for global interrupt + queue control state sensor (9005) must be + (2ibm,interrupt-server#-size) - 1- the gserver# of the + global queue to be sensed as given in the + + “ibm,ppc-interrupt-gserver#s” property. + + + For exploitation compatibility mode, the index value must be 0, + which is the only supported global server index in exploitation + compatibility mode. + + - + - Note: on platforms that do not report + Note: on platforms that do not report “ibm,interrupt-server#-size” property, the assumed value of the size of the interrupt server number is 8.
- +
- +
Power Control - +
<emphasis>set-power-level</emphasis> This RTAS call is used to set the power level of a power domain to either on or off. - + - R1-R1--1. - RTAS must implement the + RTAS must implement the set-power-level call using the argument call buffer - defined by + defined by . - + Argument Call Buffer <emphasis>set-power-level</emphasis> @@ -6975,7 +6983,7 @@ - Token for + Token for set-power-level @@ -7051,35 +7059,35 @@
- + - R1-R1--2. Power_domain must be a power domain identified in the OF device tree. - + - R1-R1--3. Level must be 100 for full power and 0 for off. - + - R1-R1--4. The set-power-level call - must return the power level actually set in the + must return the power level actually set in the Actual_level output parameter. Software Implementation Notes: - - + + The set-power-level(0,0) call, if implemented, removes power from the root domain, turning off power to all domains. The external @@ -7087,106 +7095,106 @@ primitive power-off also removes power from the system, but permits specifying the events which can turn power back on. - + - The implemented values for the + The implemented values for the Level parameter for each power domain are defined in the OF device tree. - + - + - R1-R1--5. The set-power-level RTAS call, when implemented, must - return either a -2 or a 990x return code if the + return either a -2 or a 990x return code if the set-power-level operation specified in the RTAS call is going to exceed 1 millisecond in duration (where value of x gives a hint as to the duration of the busy; see text). - - A single + + A single set-power-level operation may require an extended period of time for execution. Following the initiation of the hardware - operation to change the power level, if the + operation to change the power level, if the set-power-level call returns prior to successful - completion of the operation, the call returns either a - Status code of -2 or 990x. A + completion of the operation, the call returns either a + Status code of -2 or 990x. A Status code of -2 indicates that RTAS may be capable - of doing useful processing immediately. A + of doing useful processing immediately. A Status code of 990x indicates that the platform requires an extended period of time, and hints at how much time is - required. Neither the 990x nor the -2 + required. Neither the 990x nor the -2 Status codes implies that the platform has initiated - the operation, but it is expected that the 990x + the operation, but it is expected that the 990x Status is used only if the operation had been initiated. - 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 set-power-level with the same power domain token. - However, software may issue the + However, software may issue the set-power-level call again either earlier or later than this. Software Implementation Note: - In Requirement + In Requirement , a return code of -2 or 990x may either mean that the operation was initiated but not completed, or may mean that the operation was not initiated at all. Firmware Implementation Notes: - - + + If the RTAS initiates and returns before successful completion - of the operation, then it needs to handle the split of a + of the operation, then it needs to handle the split of a set-power-level operation across multiple calls. - + - It is the firmware’s responsibility to not return a + It is the firmware’s responsibility to not return a Status of 0 (success) until the operation is complete, and that may require performing an operation such as a delay operation or querying the hardware for power good status. In the former case, the firmware needs to save state between the calls to the same power domain number, until the operation is complete. - + - The + The set-power-level RTAS call may be called to set the power level of other power domains after the initiation to other domains and before the operation to those other domains are complete. If - necessary, the - set-power-level call may return a -2 or 990x + necessary, the + set-power-level call may return a -2 or 990x Status to those calls without initiating the operation, if multiple simultaneous operations are not feasible. - - + +
- +
<emphasis>get-power-level</emphasis> - + - R1-R1--1. - RTAS must implement the + RTAS must implement the get-power-level call using the argument call buffer - defined by + defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>get-power-level</emphasis> @@ -7222,7 +7230,7 @@ - Token for + Token for get-power-level @@ -7287,39 +7295,39 @@
- + - R1-R1--2. Power_domain must be a power domain identified in the OF device tree. - Software Implementation Note: The + Software Implementation Note: The get-power-level call only returns information about power levels whose state is readable in hardware. It does not need to remember the last set state and return that value. - +
- +
<emphasis>power-off</emphasis> This primitive turns power off on a system which is equipped to perform a software-controlled power off function. - + - R1-R1--1. If software controlled power-off hardware is - present, the + present, the power-off function must turn off power to the - platform, using the argument call buffer described in + platform, using the argument call buffer described in . - + <emphasis>power-off</emphasis> Argument Call Buffer @@ -7356,7 +7364,7 @@ - Token for + Token for power-off @@ -7423,37 +7431,37 @@
- + - R1-R1--2. If software controlled power-off hardware is present, Power_on_mask, which is passed in two parts to permit a possible 64 events even on 32-bit implementations, - must be a bit mask of power on triggers, or if the + must be a bit mask of power on triggers, or if the “power-on-triggers” property is absent - from the - /rtas node, a value of 0 must be used for - Power_on_mask_hi and + from the + /rtas node, a value of 0 must be used for + Power_on_mask_hi and Power_on_mask_lo. - + - R1-R1--3. - Platforms must omit the - “power-on-triggers” property from the + Platforms must omit the + “power-on-triggers” property from the /rtas node. - + Implementation Note: The power on triggers, which - were removed from this architecture, are documented in the + were removed from this architecture, are documented in the , for legacy reasons. - + Defined Power On Triggers @@ -7575,9 +7583,9 @@
- + - R1-R1--4. For the System Parameters option: If software @@ -7587,27 +7595,27 @@ - +
- +
<emphasis>ibm,power-off-ups</emphasis> This RTAS call manages the system power-off function in systems which may have power backed up with an Uninterruptible Power Supply (UPS). - + - R1-R1--1. For platforms that support a platform - controlled Uninterruptible Power Supply (UPS), the + controlled Uninterruptible Power Supply (UPS), the ibm,power-off-ups function must be implemented, whether a platform controlled UPS is present or not, using the argument - call buffer described in + call buffer described in . - + Argument Call Buffer <emphasis>ibm,power-off-ups</emphasis> @@ -7645,7 +7653,7 @@ - Token for + Token for ibm,power-off-ups @@ -7688,73 +7696,73 @@
- + - R1-R1--2. If a platform controlled UPS is present, then the ibm,power-off-ups RTAS call must turn off system power while enabling platform auto restart upon restoration of system - power, according to the platform_auto_power_restart policy described in + power, according to the platform_auto_power_restart policy described in , and must not return, otherwise, the call must not turn off system power and must not return. - + - R1-R1--3. If a platform controlled UPS is not - present, then the + present, then the ibm,power-off-ups RTAS call must turn off system power while enabling platform auto restart upon restoration of system - power, according to the platform_auto_power_restart policy described in + power, according to the platform_auto_power_restart policy described in , and must not return, otherwise, the call must not turn off system power and must not return. - + Software Implementation Notes: - - + + - Supporting + Supporting ibm,power-off-ups, allows a system to be shutdown due to a report that the system was running under UPS power for systems - with a platform managed UPS. As opposed to + with a platform managed UPS. As opposed to power-off, ibm,power-off-ups, permits the operating system to be restarted when power is restored after a loss of external power. - + The report that a system needs to be shutdown due to running under a UPS would be given by the platform as an EPOW event with EPOW event modifier being given as, 0x02 = Loss of utility power, system is - running on UPS/Battery, as described in section + running on UPS/Battery, as described in section . - + - If the RTAS + If the RTAS ibm,power-off-ups call is supported by the platform, it will also allow a shutdown with a subsequent restart when power is restored for systems running with a UPS that is not under platform control. This presumes that the OS has some external means of recognizing - when running under UPS power to initiate the + when running under UPS power to initiate the ibm,power-off-ups call. - - + +
@@ -7765,32 +7773,32 @@ and reboot the system in a new mode. For example, a different OS level may need to be loaded, or the same OS may need to be rebooted with different settings of System Environment Variables. - +
<emphasis>system-reboot</emphasis> - + - R1-R1--1. - RTAS must implement a + RTAS must implement a system-reboot call which resets all processors and all attached devices. After reset, the system must be booted with the - current settings of the System Environment Variables (refer to + current settings of the System Environment Variables (refer to for more information). - + - R1-R1--2. - The RTAS + The RTAS system-reboot call must be implemented using the - argument call buffer defined by + argument call buffer defined by . - + Argument Call Buffer <emphasis>system-reboot</emphasis> @@ -7828,7 +7836,7 @@ - Token for + Token for system-reboot @@ -7872,35 +7880,35 @@ - - Hardware Implementation Note: + + Hardware Implementation Note: The platform must be able to perform a system reset and reboot. On a multiprocessor system, this should be a hard reset to the processors. - +
<emphasis>ibm,update-flash-64-and-reboot</emphasis> - The + The ibm,update-flash-64-and-reboot function is described in this section. It does not return to the OS if successful. This call supports RTAS instantiated in 32 bit mode to access storage at addresses - above 4GB. In an exception to the LPAR Requirement + above 4GB. In an exception to the LPAR Requirement this call supports block lists being outside of the Real Mode Area (RMA) as long as the initial block - list is at an address below the limits of the cell size of the + list is at an address below the limits of the cell size of the Block_list argument. - + - R1-R1--1. - The argument call buffer for the + The argument call buffer for the ibm,update-flash-64-and-reboot RTAS call must - correspond to the definition in + correspond to the definition in . - +
Argument Call Buffer <emphasis>ibm,update-flash-64-and-reboot</emphasis> @@ -7938,7 +7946,7 @@ - Token for + Token for ibm,update-flash-64-and-reboot @@ -7991,7 +7999,7 @@ - The + The Status of 0 is never returned, because this RTAS call does not return if successful. @@ -8037,19 +8045,19 @@
- + - R1-R1--2. - The RTAS - ibm,update-flash-64-and-reboot call - Block_list on platforms that do not present the + The RTAS + ibm,update-flash-64-and-reboot call + Block_list on platforms that do not present the “ibm,flash-block-version” property in the - OF - /rtas node must conform to the definition shown in + OF + /rtas node must conform to the definition shown in . - + Format of Block List @@ -8057,7 +8065,7 @@ - Length of + Length of Block_list in bytes @@ -8093,76 +8101,76 @@
- + - R1-R1--3. - The - ibm,update-flash-64-and-reboot RTAS call + The + ibm,update-flash-64-and-reboot RTAS call Block_list must be a sequence of 64 bit cells. - + - R1-R1--4. - Memory blocks referenced in the - ibm,update-flash-64-and-reboot RTAS call + Memory blocks referenced in the + ibm,update-flash-64-and-reboot RTAS call Block_list must reside in System Memory outside that reserved for firmware (both the RTAS data area and OF’s memory defined by real-base and real-size). - + - R1-R1--5. - The block list referenced by the - Block_list argument to the + The block list referenced by the + Block_list argument to the ibm,update-flash-64-and-reboot RTAS call must be in System Memory below the maximum address supported by the RTAS instantiated cell size. - + - R1-R1--6. The addresses of memory blocks referenced - by the - ibm,update-flash-64-and-reboot RTAS call + by the + ibm,update-flash-64-and-reboot RTAS call Block_list must align tn a 4 KB boundary. - + - R1-R1--7. - A memory block, included in the - ibm,update-flash-64-and-reboot RTAS call + A memory block, included in the + ibm,update-flash-64-and-reboot RTAS call Block_list, must not cross a 256MB boundary. - + - R1-R1--8. The ibm,update-flash-64-and-reboot call must test the image to make sure it has the right format and is not damaged, update the - flash from the + flash from the Block_list and then perform a system reset and - reboot, as for the + reboot, as for the system-reboot call. - + Hardware and Software Implementation Note: Platform specific information should be embedded in the flash images to identify @@ -8175,43 +8183,43 @@ Software Implementation Notes: - - + + The execution time for this calls may be in the order of seconds, rather than “a few tens of microseconds” as noted on - page + page . - + The RTAS flash update programs should display progress, completion, and error information while the flash update is underway, if possible. - + - The OS does not expect a return from the + The OS does not expect a return from the ibm,update-flash-64-and-reboot call other than for cases where the hardware cannot be accessed, the flash image is unacceptable to the RTAS flash update program, the result of the update corrupted the flash, or the platform could not be rebooted. - - + +
- +
Flash Update with Discontiguous Block Lists - The property - “ibm,flash-block-version” (see + The property + “ibm,flash-block-version” (see ) is defined to describe the - following definition and operation of the - Block_list shown in + following definition and operation of the + Block_list shown in . - + - Format of Discontiguous + <title>Format of Discontiguous <emphasis>Block_list</emphasis> @@ -8222,7 +8230,7 @@ VER - Length of + Length of Block_list in bytes @@ -8230,7 +8238,7 @@ - Address of + Address of Block_list extension @@ -8273,125 +8281,125 @@
Where: - - + + - VER (1 byte in length) indicates the version of the + VER (1 byte in length) indicates the version of the Block_list. - + - Length of the - Block_list in bytes indicates the size of this + Length of the + Block_list in bytes indicates the size of this Block_list, including the header cell and the cell - with the address of the + with the address of the Block_list extension. - + - Address of the + Address of the Block_list extension indicates the location of the - next - Block_list. 0x00 indicates no additional + next + Block_list. 0x00 indicates no additional Block_list extension. - + Address of memory area 1 (2 . . . n) indicates the location of this portion of the flash image. - + Length of memory area 1 (2 . . . n) indicates the length of this portion of the flash image. - - - + + + - R1-R1--1. - If VER is 0x01, the - Block_list must be formatted as in + If VER is 0x01, the + Block_list must be formatted as in . - + - R1-R1--2. - If VER is 0x01, the + If VER is 0x01, the Block_list parameter in the function call or the - Address of the - Block_list extension, if not 0x00, must point to a - Block_list cell containing VER and Length of the + Address of the + Block_list extension, if not 0x00, must point to a + Block_list cell containing VER and Length of the Block_list. - + - R1-R1--3. - If VER is 0x01, the Address of the + If VER is 0x01, the Address of the Block_list extension parameter must be 0x00 to indicate that there are no further extensions. - + - R1-R1--4. - The VER byte must exist in the - Block_list and in each + The VER byte must exist in the + Block_list and in each Block_list extension. - + - R1-R1--5. - If the platform supports the property + If the platform supports the property “ibm,flash-block-version” with value 0x01, it must also support the default value 0x00. - - The + + The Block_list format allows flexibility in the size and page requirements for the block lists. Page alignment is not required for the lists or extensions. They may run across contiguous pages with the control being the length of each list or extension and with the end being the 0x00 pointer.
- +
<emphasis>ibm,manage-flash-image</emphasis> - - The + + The ibm,manage-flash-image RTAS call supports systems having a “temporary” and “permanent” flash image areas. It allows the user to commit the temporary flash image by copying it to the permanent image area. It also allows the user to reject the temporary flash image by overwriting it with the permanent flash image. - + - R1-R1--1. - The RTAS + The RTAS ibm,manage-flash-image call must be implemented using - the argument call buffer defined by + the argument call buffer defined by . - + Argument Call Buffer <emphasis>ibm,manage-flash-image</emphasis> @@ -8488,66 +8496,66 @@
- + - R1-R1--2. The ibm,manage-flash-image RTAS call must not change the - system flash and must return a + system flash and must return a Status of value -9001 when called with a request to reject the temporary firmware image when not running on the permanent firmware image. - + - R1-R1--3. The ibm,manage-flash-image RTAS call must not change the - system flash and must return a + system flash and must return a Status of value -9001 when called with a request to commit the temporary firmware image when not running on the temporary firmware image. - + Platform Implementation Note: In platforms supporting two firmware image areas, platforms always apply updates to the temporary - image area. The RTAS call + image area. The RTAS call ibm,manage-flash-image is the normal means by which a temporary image is committed to the permanent side. However, if a platform is running from a temporary image when an update is to be applied, then the platform may automatically commit the current temporary image to the permanent side to allow the new image to be updated to the - temporary image area. The + temporary image area. The ibm,validate-flash-image RTAS call is used to determine what would result from an attempt to update a FLASH image taking in to account the image to be updated and the current image being executed.
- +
<emphasis>ibm,validate-flash-image</emphasis> - - The + + The ibm,validate-flash-image RTAS call allows OS service code to determine if a candidate flash image is valid, if the partition has authority to update the flash image, and what the resulting flash levels will be after performing the update. - + - R1-R1--1. The ibm,validate-flash-image RTAS call must be - implemented using the argument call buffer described in + implemented using the argument call buffer described in . - + Argument Call Buffer <emphasis>ibm,validate-flash-image</emphasis> @@ -8656,7 +8664,7 @@ Token to identify what will happen if update is attempted - with this token, described in Requirement + with this token, described in Requirement . @@ -8665,68 +8673,68 @@
- + - R1-R1--2. - The - ibm,validate-flash-image RTAS call + The + ibm,validate-flash-image RTAS call Buffer Ptr parameter must be a real address representing the starting address of a minimum 4 K buffer, contiguous in real memory. - + - R1-R1--3. - On input, the + On input, the ibm,validate-flash-image RTAS call buffer pointed to - by the + by the Buffer Ptr parameter must contain the first 4 KB of the candidate flash image to be validated. - + - R1-R1--4. - For the LPAR option: The + For the LPAR option: The ibm,validate-flash-image RTAS call buffer described - in Requirement + in Requirement must be in the partition's RMA. - + - R1-R1--5. - On exit from the + On exit from the ibm,validate-flash-image RTAS call, RTAS must place - the following data in the buffer, starting at the address in the + the following data in the buffer, starting at the address in the Buffer Ptr parameter: - - + + “MI”<sp> current-T-image <sp> current-P-image <0x0A> - + “MI”<sp> new-T-image <sp> new-P-image <0x00> - + “ML”<sp> current-T-image <sp> current-P-image <0x0A> - + “ML”<sp> new-T-image <sp> new-P-image <0x00> @@ -8735,11 +8743,11 @@ “MG”<sp>current-T-img-ga-date<sp>current-P-img-ga-date<0x0A> - + “MG”<sp>new-T-img-ga-date<sp>new-P-img-ga-date<0x0A> - + “MG”<sp>input-image-ga-date<0x0A> @@ -8747,9 +8755,9 @@ “ME”<sp>fw-service-entitlement-expiration-date<0x00> - - - In Requirement + + + In Requirement , current-T-image and current-P-image are the fixpack microcode image names currently on the Temporary and Permanent sides, respectively, and new-T-image and @@ -8763,19 +8771,19 @@ current-P-image, respectively. - + - R1-R1--6. - On exit from the - ibm,validate-flash-image RTAS call, the + On exit from the + ibm,validate-flash-image RTAS call, the Update Results Token output must be updated with one - of the values in + of the values in . This list is in order; firmware must provide the first value in the list which would be true if an update is attempted: - + Update Results Token Values @@ -8856,8 +8864,8 @@ 7 - No update done, the candidate image's release date is later - than the system's firmware service entitlement date - service + No update done, the candidate image's release date is later + than the system's firmware service entitlement date - service warranty period has expired @@ -8876,26 +8884,26 @@ - + - +
<emphasis>ibm,activate-firmware</emphasis> - - The + + The ibm,activate-firmware allows an OS to activate a new version of firmware that has been updated in the platform flash memory after the partition was started. - + - R1-R1--1. The ibm,activate-firmware RTAS call must be implemented - using the argument call buffer described in + using the argument call buffer described in . - +
Argument Call Buffer <emphasis>ibm,activate-firmware</emphasis> @@ -8981,7 +8989,7 @@ - + Software implementation Note: The OS should expect that a number of calls may be required to accomplish firmware activation, @@ -8992,7 +9000,7 @@ - +
SMP Support In a Symmetric Multiprocessor (SMP) system, the platform needs the @@ -9002,19 +9010,19 @@ - R1-R1--1. - (Merged into Requirement + (Merged into Requirement ) - + - R1-R1--2. - (Merged into Requirement + (Merged into Requirement ) @@ -9022,40 +9030,40 @@
<emphasis>stop-self</emphasis> - + The stop-self primitive causes a processor thread to stop processing OS or user code, and to enter a state in which it is only - responsive to the - start-cpu RTAS primitive. This is referred to as the - RTAS + responsive to the + start-cpu RTAS primitive. This is referred to as the + RTAS stopped state. - + - R1-R1--1. A stop-self RTAS call must place the calling processor - thread in the - RTAS + thread in the + RTAS stopped state. This call must be implemented using - the argument call buffer defined by + the argument call buffer defined by . - + - R1-R1--2. RTAS must insure that a processor thread - in the RTAS + in the RTAS stopped state does not checkstop or otherwise fail if a machine check or soft reset exception occurs. Processor threads in this state receive the exception, but must perform a null action and remain in - the RTAS + the RTAS stopped state. - +
Argument Call Buffer <emphasis>stop-self</emphasis> @@ -9093,7 +9101,7 @@ - Token for + Token for stop-self @@ -9135,7 +9143,7 @@
Software Implementation Note: If this call succeeds, it does not - return. The CPU thread waits for some other processor thread to issue a + return. The CPU thread waits for some other processor thread to issue a start-cpu targeted to this processor thread. Firmware Implementation Note: In an LPAR environment @@ -9148,20 +9156,20 @@ another partition. - + - R1-R1--3. - Platforms which support the enhanced - stop-self RTAS behavior must include the name only + Platforms which support the enhanced + stop-self RTAS behavior must include the name only “ibm,integrated-stop-self” OF property, - under the + under the /rtas node, and prior to placing a processor in the stopped state, flush and disable any caches/memory exclusively used by the issuing processor. - Architecture Note: In Requirement + Architecture Note: In Requirement , an exclusively used cache means that no other running processor currently needs the cache for normal operation, even if the cache could potentially be shared with @@ -9170,70 +9178,70 @@ processor threads. - + - R1-R1--4. - Execution of the + Execution of the stop-self call by the last active processor thread must cause the firmware to recover all the resources owned by the executing OS image for use per platform policy. - +
- +
<emphasis>start-cpu</emphasis> - + The start-cpu primitive is used to cause a processor thread which is currently in the RTAS stopped state to start processing at an indicated location. - + - R1-R1--1. A start-cpu RTAS call must remove the processor thread - specified by the - CPU_id parameter from the RTAS + specified by the + CPU_id parameter from the RTAS stopped state. This call must be implemented using - the argument call buffer defined by + the argument call buffer defined by . - + - R1-R1--2. - The processor thread specified by the - CPU_id parameter must be in the RTAS + The processor thread specified by the + CPU_id parameter must be in the RTAS stopped state entered because of a prior call by that - processor to the + processor to the stop-self primitive. - + - R1-R1--3. - When a processor thread exits the RTAS + When a processor thread exits the RTAS stopped state, it must begin execution in real mode, with the MSR in the same state as from a system reset interrupt (except for the MSRHV bit which is on if not running under a hypervisor and off if running under a hypervisor) at the real location indicated by - the + the Start_location parameter, with register R3 set to the - value of parameter - Register_R3_contents and the MSR as defined in + value of parameter + Register_R3_contents and the MSR as defined in . All other register contents are indeterminate. - + Argument Call Buffer <emphasis>start-cpu</emphasis> @@ -9271,7 +9279,7 @@ - Token for + Token for start-cpu @@ -9352,14 +9360,14 @@ - + - Note: Requirement + Note: Requirement applies to the start-cpu RTAS call. At the completion of start-cpu, the caches to be used by the specified processor must have been initialized and the state bits made accurate prior to beginning execution at the start address. - +
Machine State Register (MSR) State in Started Processor @@ -9633,25 +9641,25 @@
- +
<emphasis>query-cpu-stopped state</emphasis> - + The query-cpu-stopped-state primitive is used to query a different processor thread to determine its status with respect to the RTAS stopped state. - + - R1-R1--1. - A query-cpu-stopped-state RTAS call must return the - CPU_status of the processor thread specified by the + A query-cpu-stopped-state RTAS call must return the + CPU_status of the processor thread specified by the Cpu_id parameter. This call must be implemented using - the argument call buffer defined by + the argument call buffer defined by . - + Argument Call Buffer <emphasis>query-cpu-stopped-state</emphasis> @@ -9689,7 +9697,7 @@ - Token for + Token for query-cpu-stopped-state @@ -9751,7 +9759,7 @@ 0: The processor thread is in the RTAS stopped state - 1: + 1: stop-self is in progress 2: The processor thread is not in the RTAS stopped state @@ -9763,18 +9771,18 @@ - + Firmware Implementation Note: RTAS serialization may be required between the - stop-self and the + stop-self and the query-cpu-stopped-state calls. - Software Implementation Note: The OS performs a + Software Implementation Note: The OS performs a stop-self on the desired processor thread, then periodically call s query-cpu-stopped-state on another processor thread - until the desired processor thread is stopped. Before calling + until the desired processor thread is stopped. Before calling set-power-level to power off the desired processor, or isolate the logical CPU, the platform requires that all processor threads be in the RTAS stopped state. @@ -9785,115 +9793,115 @@
Miscellaneous RTAS Calls - +
<emphasis>ibm,os-term</emphasis> - + This RTAS call is provided for the OS to indicate to the platform that it has terminated normal operation. A string of information is passed to the platform. - A call to the + A call to the ibm,os-term RTAS function implies the following to the platform: - - + + Any platform reporting and recovery policies may now take effect. - + - The OS may no longer be issuing periodic + The OS may no longer be issuing periodic event-scan requests, so surveillance monitoring does not continue. - + - All devices not marked + All devices not marked “used-by-rtas” are released by the OS (including, for example, native serial ports used by a service processor). - + The OS no longer responds to any EPOW events, so it is up to the platform to take any appropriate actions for such events. - - + + Due to the above implications, the platform may take actions (for example, a service processor “call home”) that could conflict with normal processing of further RTAS requests. However, since the OS has entered a “live halt” state, the list of RTAS functions that it still needs is relatively small. The list of RTAS functions that - the platform might expect to see after + the platform might expect to see after ibm,os-term includes: - - + + nvram-fetch - + nvram-store - + display-character - + power-off - + ibm,power-off-ups - + system-reboot - + check-exception for machine checks (Although the OS - may still react normally to a machine check condition by calling + may still react normally to a machine check condition by calling check-exception, it might not process a returned - error log. It is allowable for + error log. It is allowable for check-exception to not return an extended log when in this state.) - - + + If a platform has a service processor, and a policy has been established for actions to be taken by the service processor upon receiving notice of OS termination, the service processor may complete those actions and a return to the CPU from this call may never occur. If the call does return, the OS performs its own termination policy. - - When the platform supports extended + + When the platform supports extended ibm,os-term behavior, the return to the RTAS will always occur unless there is a kernel assisted dump active as initiated - by an + by an ibm,configure-kernel-dump call. - Platforms capable of supporting this extended + Platforms capable of supporting this extended ibm,os-term behavior will so indicate by presenting - the + the “ibm,extended-os-term” RTAS property in the OF device tree. - + - R1-R1--1. - RTAS must implement an + RTAS must implement an ibm,os-term call using the argument call buffer - defined by + defined by to receive a termination string from the OS. - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,os-term</emphasis> @@ -9929,7 +9937,7 @@ - Token for + Token for ibm,os-term @@ -9987,51 +9995,51 @@ location or saved in the platform for later remote access. - + - R1-R1--2. The ibm,os-term call must disable surveillance. - + - R1-R1--3. During the machine check and soft reset - handlers, the platform must support access to the + handlers, the platform must support access to the ibm,os-term RTAS function. - + - R1-R1--4. - If the + If the ibm,os-term call does not return to the caller, the platform must honor the partition_auto_restart system parameter value. - + - R1-R1--5. - For platforms supporting extended - ibm,os-term behavior, the + For platforms supporting extended + ibm,os-term behavior, the ibm,os-term call must always return unless there is - an active kernel assisted dump configured as specified by an + an active kernel assisted dump configured as specified by an ibm,configure-kernel-dump RTAS call. - + - Platform implementation note: The + Platform implementation note: The ibm,os-term RTAS call allows for the case where the OS and platform may share an I/O device such as a TTY where the OS would have use of the device normally, and the platform use when the OS has @@ -10041,17 +10049,17 @@ also used for the call-home by the platform, the platform should not initiate the call home until after the partition shuts down. - +
<emphasis>Ibm,exti2c</emphasis> - - For support of platforms which require an external + + For support of platforms which require an external I2C bus, a special port to the service processor is required. The EXTI2C option is designed to control specific external - devices. Designers cannot assume that an arbitrary + devices. Designers cannot assume that an arbitrary I2C device may be substituted. - The - ibm,exti2c call provides a single channel to the + The + ibm,exti2c call provides a single channel to the I2C bus. Through this channel, software can read or write up to 256 bytes from/to an addressed resource within an address space between X’000000 and X’FFFFFF. Reference the @@ -10065,46 +10073,46 @@ has a different value from that of the last call, a new operation is started, with any previous operation being aborted. An input Buffer Pointer value that is the same as that used on the previous call - indicates a continuation of the last operation, given that the + indicates a continuation of the last operation, given that the Status of the last call was not 0 (success) or -1 (hardware error). These terminating statuses reset the channel. - Using software must manage serialization to the + Using software must manage serialization to the ibm,exti2c channel across multiple calls for the same I2C operation. - A single + A single ibm,exti2c operation may require an extended period of processing by background hardware. During this time, RTAS returns - either a - Status code of -2 or 990x. A + either a + Status code of -2 or 990x. A Status of -2 indicates that RTAS may be capable of doing useful processing immediately. - A + A Status code of 990x indicates that the platform requires an extended period of time to perform the operation. It is suggested that software delay for 10 raised to the x milliseconds before calling ibm,exti2c with the same Buffer Pointer value, however, software may call again earlier or later. - A + A Status code of -1 indicates either a general error - associated with the local + associated with the local I2C hardware (service processor) or that the channel has been corrupted due to other error conditions not associated with the I2C operation. If the buffer is changed, as when an - error code is returned, the RTAS + error code is returned, the RTAS Status code is 0 (success). - + - R1-R1--1. - For the EXTI2C option: RTAS must implement an + For the EXTI2C option: RTAS must implement an ibm,exti2c call using the argument call buffer - defined by + defined by to allow communications with special hardware. - +
ibm,exti2c Argument Call Buffer @@ -10141,7 +10149,7 @@ - Token for + Token for ibm,exti2c @@ -10197,26 +10205,26 @@
- + - R1-R1--2. For the EXTI2C option: The Buffer Pointer must point - to a contiguous real storage area large enough to contain the + to a contiguous real storage area large enough to contain the I2C command and any associated data (maximum of 261 bytes). - + - R1-R1--3. For the EXTI2C option: The Buffer format for the - write operation must be as defined in + write operation must be as defined in . - + EXTI2C Buffer Write Operation Format @@ -10335,24 +10343,24 @@
- Firmware and Software Implementation Note: When the + Firmware and Software Implementation Note: When the ibm,exti2c RTAS call write operation returns after the operation has been enqueued by the firmware but prior to completion - by the hardware (therefore the operation status is truly not known), the - ibm,exti2c RTAS call can return a + by the hardware (therefore the operation status is truly not known), the + ibm,exti2c RTAS call can return a Status of 0 (success) with the buffer unmodified. - + - R1-R1--4. For the EXTI2C option: The Buffer format for a read - operation, if supported, must be as defined in + operation, if supported, must be as defined in . - + EXTI2C Buffer Read Operation Format (Optional) @@ -10481,53 +10489,53 @@
- + - R1-R1--5. For the EXTI2C option: If read operations are not supported and a read operation is attempted, then the platform must - return a + return a Status of -3. - + - R1-R1--6. For the EXTI2C option: The maximum total Extended Delay imposed by the - ibm,exti2c command for a single + ibm,exti2c command for a single I2C operation must be less than 2 seconds. - + - R1-R1--7. - For the EXTI2C option: When the + For the EXTI2C option: When the ibm,exti2c RTAS call returns an EXTI2C buffer - containing an I2C operation error code, the RTAS + containing an I2C operation error code, the RTAS Status code must be 0 (success). - + - Firmware and Software Implementation Note: When the + Firmware and Software Implementation Note: When the ibm,exti2c RTAS call returns after the operation has been enqueued by the firmware but prior to completion by the hardware - (therefore the operation status is truly not known), the - ibm,exti2c RTAS call can return a + (therefore the operation status is truly not known), the + ibm,exti2c RTAS call can return a Status of 0 (success) with the buffer unmodified.
- +
PowerPC External Interrupt Option The RTAS calls used to access the facilities of the PowerPC @@ -10537,45 +10545,45 @@ Note: These RTAS calls make the PowerPC External Interrupt option Logical Partition (LPAR) ready. - +
<emphasis>ibm,get-xive</emphasis> - + - R1-R1--1. For the PowerPC External Interrupt option: RTAS must - implement an + implement an ibm,get-xive call using the argument call buffer - defined by + defined by . - + - R1-R1--2. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,get-xive call must be reentrant to the number of processors on the platform. - + - R1-R1--3. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,get-xive argument call buffer for each simultaneous call must be physically unique. - + - R1-R1--4. For the PowerPC External Interrupt option: The @@ -10584,37 +10592,37 @@ ibm,set-xive call (priority initialized to least favored level by firmware at boot), of the External Interrupt Vector Entry associated with the interrupt number provided as an input argument - unless prevented by Requirement + unless prevented by Requirement . - + - R1-R1--5. - For the PowerPC External Interrupt option: The - ibm,get-xive call must return the + For the PowerPC External Interrupt option: The + ibm,get-xive call must return the Status of -3 (Argument Error) for an unimplemented - Interrupt # (not reported via an + Interrupt # (not reported via an “interrupt-ranges” property). - + - R1-R1--6. For the PowerPC External Interrupt option combined with the - Platform Reserved Interrupt Priority Level option: The - ibm,get-xive call must return the + Platform Reserved Interrupt Priority Level option: The + ibm,get-xive call must return the Status of -3 (Argument Error) for an platform - reserved interrupt priority (reported via an the + reserved interrupt priority (reported via an the “ibm,plat-res-int-priorities” property). - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,get-xive</emphasis> @@ -10650,7 +10658,7 @@ - Token for + Token for ibm,get-xive @@ -10679,7 +10687,7 @@ Interrupt # - From + From “interrupt-ranges” property @@ -10707,7 +10715,7 @@ 0x0 - 2 - “ibm,interrupt-server#-size” + “ibm,interrupt-server#-size” @@ -10727,90 +10735,90 @@ - + - +
<emphasis>ibm,set-xive</emphasis> - + - R1-R1--1. For the PowerPC External Interrupt option: RTAS must - implement an + implement an ibm,set-xive call using the argument call buffer - defined by + defined by . - + - R1-R1--2. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,set-xive call must be reentrant to the number of processors on the platform. - + - R1-R1--3. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,set-xive argument call buffer for each simultaneous call must be physically unique. - + - R1-R1--4. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,set-xive call must set values of the server number and priority fields of the External Interrupt Vector Entry (XIVE) and/or firmware saved priority value (if the interrupt source controller does not use an interrupt Enable Register and the interrupt source is masked off, either due to a previous ibm,int-off call or because the interrupt source was - never enabled with an + never enabled with an ibm,int-on call since boot), associated with the interrupt number provided as an input argument unless prevented by - Requirement + Requirement . - + - R1-R1--5. - For the PowerPC External Interrupt option: The - ibm,set-xive call must return the + For the PowerPC External Interrupt option: The + ibm,set-xive call must return the Status of -3 (Argument Error) for an unimplemented Interrupt number. - + - R1-R1--6. For the PowerPC External Interrupt plus the Platform Reserved - Interrupt Priority Level option: The - ibm,set-xive call must return the + Interrupt Priority Level option: The + ibm,set-xive call must return the Status of -3 (Argument Error) for an reserved - Priority value (as reported via an + Priority value (as reported via an “ibm,plat-res-int-priorities” property). - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,set-xive</emphasis> @@ -10846,7 +10854,7 @@ - Token for + Token for ibm,set-xive @@ -10889,8 +10897,7 @@ 0x00 - 2 - - “ibm,interrupt-server#-size” + “ibm,interrupt-server#-size” @@ -10924,87 +10931,87 @@ - + - +
<emphasis>ibm,int-off</emphasis> - + - R1-R1--1. For the PowerPC External Interrupt option: RTAS must - implement an + implement an ibm,int-off call using the argument call buffer - defined by + defined by . - + - R1-R1--2. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-off call must be reentrant to the number of processors on the platform. - + - R1-R1--3. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-off argument call buffer for each simultaneous call must be physically unique. - + - R1-R1--4. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-off call must disable interrupts from the interrupt source associated with the interrupt number provided as an - input argument unless prevented by Requirement + input argument unless prevented by Requirement . - + - R1-R1--5. For the PowerPC External Interrupt option: If the - interrupt source controller uses an Interrupt Enable Register, the + interrupt source controller uses an Interrupt Enable Register, the ibm,int-off call must reset the mask bit associated with the specified interrupt number; or if the interrupt source - controller does not use an interrupt Enable Register, the + controller does not use an interrupt Enable Register, the ibm,int-off call must save the priority value of the - XIVE for later restoration by the - ibm,int-on call, or presentation by the + XIVE for later restoration by the + ibm,int-on call, or presentation by the ibm,get-xive call and set the priority value of the XIVE to the least favored priority value (0xFF), unless prevented by - Requirement + Requirement . - + - R1-R1--6. - For the PowerPC External Interrupt option: The - ibm,int-off call must return the + For the PowerPC External Interrupt option: The + ibm,int-off call must return the Status of -3 (Argument Error) for an unimplemented Interrupt number. - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,int-off</emphasis> @@ -11040,7 +11047,7 @@ - Token for + Token for ibm,int-off @@ -11096,85 +11103,85 @@ - + - +
<emphasis>ibm,int-on</emphasis> - + - R1-R1--1. For the PowerPC External Interrupt option: RTAS must - implement an + implement an ibm,int-on call using the argument call buffer - defined by + defined by . - + - R1-R1--2. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-on call must be reentrant to the number of processors on the platform. - + - R1-R1--3. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-on argument call buffer for each simultaneous call must be physically unique. - + - R1-R1--4. - For the PowerPC External Interrupt option: The + For the PowerPC External Interrupt option: The ibm,int-on call must enable interrupts from the interrupt source associated with the interrupt number provided as an - input argument unless prevented by Requirement + input argument unless prevented by Requirement . - + - R1-R1--5. For the PowerPC External Interrupt option: If the interrupt source controller uses an Interrupt Enable Register, the ibm,int-on call must set the mask bit associated with the specified interrupt number; or if the interrupt source controller - does not use an interrupt Enable Register, the + does not use an interrupt Enable Register, the ibm,int-on call must restore the XIVE priority value - saved by the previous + saved by the previous ibm,int-off call (initialized by the firmware to the - least favored level at boot) unless prevented by Requirement + least favored level at boot) unless prevented by Requirement . - + - R1-R1--6. - For the PowerPC External Interrupt option: The - ibm,int-on call must return the + For the PowerPC External Interrupt option: The + ibm,int-on call must return the Status of -3 (Argument Error) for an unimplemented Interrupt number. - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,int-on</emphasis> @@ -11210,7 +11217,7 @@ - Token for + Token for ibm,int-on @@ -11266,13 +11273,13 @@ - + - +
MSI Support This section describes the RTAS calls required when the MSI option - is implemented. See + is implemented. See for other platform requirements for the MSI option. The Message Signaled Interrupt (MSI) and Enhanced MSI (MSI-X) @@ -11286,47 +11293,47 @@ is required. as a resource pool that is reassigned based on availability of MSIs and the need of an IOA function for more interrupts than initially - assigned. Platforms that implement the MSI option implement the - ibm,change-msi and + assigned. Platforms that implement the MSI option implement the + ibm,change-msi and ibm,query-interrupt-source-number RTAS calls. - +
<emphasis>ibm,change-msi</emphasis> - The OS uses the + The OS uses the ibm,change-msi RTAS call to query the initial number of MSIs assigned to a PCI configuration address (that is, to an IOA function) and to request a change in the number of MSIs assigned, when the platform allows for dynamic reassignment of MSIs for the IOA - function. The + function. The ibm,change-msi RTAS call allows the caller to allow the platform to select MSI or MSI-X, to specifically select MSI or MSI-X or, if LSIs are allocated by the firmware for the IOA function, to change to LSI (by removal of the MSIs assigned). The interrupt source numbers - assigned to an IOA function are queried via the - ibm,query-interrupt-source-number RTAS call. The + assigned to an IOA function are queried via the + ibm,query-interrupt-source-number RTAS call. The ibm,query-interrupt-source-number RTAS call is called iteratively, once for each interrupt assigned to the IOA function. The - interrupt source numbers returned by the + interrupt source numbers returned by the ibm,query-interrupt-source-number RTAS call are the - numbers used to control the interrupt as in the - ibm,get-xive, - ibm,set-xive, + numbers used to control the interrupt as in the + ibm,get-xive, + ibm,set-xive, ibm,int-on, and ibm,int-off RTAS calls. If a device driver is willing to live with the platform-assigned - initial number of MSIs, then the device driver does not need to use the - ibm,change-msi RTAS call, and can instead use the + initial number of MSIs, then the device driver does not need to use the + ibm,change-msi RTAS call, and can instead use the ibm,query-interrupt-source-number RTAS call to determine the number of interrupts assigned to each IOA function. An OS may abandon the effort to change the MSIs for a given - configuration address after the first call to + configuration address after the first call to ibm,change-msi and prior to a call which gets a status back indicating completion, by calling again with the same PCI - configuration address but with a + configuration address but with a Function number of 2 (set to default number of - interrupts) and a - Sequence Number of 1. RTAS never returns a - Status of -2 or 990x when the call is made with a + interrupts) and a + Sequence Number of 1. RTAS never returns a + Status of -2 or 990x when the call is made with a Function number of 2. If an OS successfully changes the number of interrupts, then it should consider removing the increase when it deconfigures the IOA @@ -11339,43 +11346,43 @@ LSIs but does not remove them, and then removing the MSIs that replaced the LSIs re-uses the same (previously removed) LSIs (mapped to the same LSI source numbers as the previous LSI source numbers). - The presence of the + The presence of the “ibm,change-msix-capable” property specifies that the platform implements the version of this RTAS call that - allows - Number Outputs equal to 4 and + allows + Number Outputs equal to 4 and Functions 3, 4 and 5. - If the - ibm,change-msi RTAS call is made with - Number Outputs equal to 4 or with - Function equal to 3 or 4 when the + If the + ibm,change-msi RTAS call is made with + Number Outputs equal to 4 or with + Function equal to 3 or 4 when the “ibm,change-msix-capable” property does - not exist in the - /rtas node, then the call will return a - Status of -3 (Invalid Parameter). Specifying + not exist in the + /rtas node, then the call will return a + Status of -3 (Invalid Parameter). Specifying Function 3 (MSI) also disables MSI-X for the - specified IOA function, and likewise specifying + specified IOA function, and likewise specifying Function 4 (MSI-X) disables MSI for the IOA function. - It is unnecessary to specify a + It is unnecessary to specify a Requested Number of Interrupts of zero when switching - between MSI and MSI-X. Specifying the - Requested Number of Interrupts to zero for either + between MSI and MSI-X. Specifying the + Requested Number of Interrupts to zero for either Function 3 or 4 removes all MSI & MSI-X interrupts from the IOA function. It is permissible to use LSI, MSI and MSI-X on different IOA functions. - The default (initial) assignment of interrupts is defined in + The default (initial) assignment of interrupts is defined in . - + - R1-R1--1. - For the MSI option: The platform must implement the + For the MSI option: The platform must implement the ibm,change-msi call using the argument call buffer - defined by + defined by . - +
<emphasis>ibm,change-msi</emphasis> Argument Call Buffer @@ -11412,7 +11419,7 @@ - Token for + Token for ibm,change-msi. @@ -11433,7 +11440,7 @@ - 3 or 4, when the + 3 or 4, when the “ibm,change-msix-capable” property is present, 3 otherwise. @@ -11458,7 +11465,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 @@ -11470,7 +11477,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 @@ -11484,26 +11491,26 @@ Determines action of this call: 0: Query only (only return actual number of MSI or MSI-X interrupts assigned to the PCI configuration address). - 1: If + 1: If Number Outputs is equal to 3, request to set to a new number of MSIs (including set to 0). - If the + If the “ibm,change-msix-capable” property exists - and + and Number Outputs is equal to 4, request is to set to a new number of MSI or MSI-X (platform choice) interrupts (including set to 0). 2: Request to set back to the default number of interrupts (also aborts a change in progress; that is, one that - has previously returned a + has previously returned a Status of -2 or 990x) - 3: (Only valid if + 3: (Only valid if “ibm,change-msix-capable” exists): Request to set to a new number of MSIs (including set to 0) - 4: (Only valid if + 4: (Only valid if “ibm,change-msix-capable” exists): Request to set to a new number of MSI-X interrupts (including @@ -11511,7 +11518,7 @@ 5: (Only valid if “ibm,change-msix-capable” exists): - Request to set to a new number of 32 bit MSI (including set to 0) + Request to set to a new number of 32 bit MSI (including set to 0) disregarding the adapter capability to support 64 bit MSI. @@ -11525,7 +11532,7 @@ The total number of MSIs being requested for the PCI configuration address. A value of 0 is specified in order to remove all MSIs for the PCI configuration address. This input - parameter is ignored by RTAS for + parameter is ignored by RTAS for Function values other than 1, 3, 4 or 5. @@ -11538,7 +11545,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. @@ -11569,10 +11576,10 @@ Number of interrupts assigned to the PCI configuration address at the successful completion of this call ( - Status of 0). For + Status of 0). For Function 1, 3, or 4, if a greater number was requested than what was previously assigned, the final - number may be less than what was requested, even though a + number may be less than what was requested, even though a Status of 0 is returned. @@ -11583,9 +11590,9 @@ - Integer to be returned as the + Integer to be returned as the Sequence Number parameter on the next call. - This output is only valid if a + This output is only valid if a Status of -2 or 990x is returned. @@ -11596,7 +11603,7 @@ - This field is only valid when the + This field is only valid when the Final Number of Interrupts is non-zero. 1: MSI @@ -11608,67 +11615,67 @@
- + - R1-R1--2. - For the MSI option: The - Final number of Interrupts and + For the MSI option: The + Final number of Interrupts and Type of Interrupts must be valid when the platform - returns a + returns a Status of 0 (Success), regardless of whether the original number and final number of interrupts assigned is different and regardless of whether or not the platform allows MSI resources to be reassigned for the specified PCI configuration address. - + - R1-R1--3. - For the MSI option: The platform must return a - Status of -3 (Parameter error) from + For the MSI option: The platform must return a + Status of -3 (Parameter error) from ibm,change-msi, with no change in interrupt - assignments if the PCI configuration address does not support MSI and - Function 3 was requested (that is, the + assignments if the PCI configuration address does not support MSI and + Function 3 was requested (that is, the “ibm,req#msi” property must exist for the - PCI configuration address in order to use - Function 3), or does not support MSI-X and - Function 4 is requested (that is, the + PCI configuration address in order to use + Function 3), or does not support MSI-X and + Function 4 is requested (that is, the “ibm,req#msi-x” property must exist for - the PCI configuration address in order to use + the PCI configuration address in order to use Function 4), or if neither MSIs nor MSI-Xs are - supported and + supported and Function 1 is requested. - + - R1-R1--4. For the MSI option: If there are zero MSIs assigned to the target IOA function but there is one or more LSIs assigned, then a - call to + call to ibm,change-msi which successfully changes the number of MSIs assigned to non-zero must also disable the LSIs in the IOA function’s configuration space and must keep the LSI platform resources available to the IOA function in the case the MSIs are removed - (see Requirement + (see Requirement ). - + - R1-R1--5. For the MSI option: If there are a non-zero number of MSIs assigned to the target IOA function and if that - IOA function originally had some LSIs assigned, then a call to + IOA function originally had some LSIs assigned, then a call to ibm,change-msi which successfully changes the number of MSIs assigned to zero must also reassign any LSIs that were originally assigned to that IOA function, using the same interrupt number that was @@ -11678,105 +11685,105 @@ space. - + - R1-R1--6. For the MSI option: If the platform supports the changing of MSIs, then it must support the reduction in the number of - interrupts by the + interrupts by the ibm,change-msi call, including setting the number of MSIs to 0. - + - R1-R1--7. - For the MSI option: On the first call of - ibm,change-msi, the + For the MSI option: On the first call of + ibm,change-msi, the Sequence Number must be a 1. - + - R1-R1--8. - For the MSI option: If - ibm,change-msi returns a + For the MSI option: If + ibm,change-msi returns a Status of -2 (Call again) or 990x (Extended Delay), - then the caller must provide on the next call to + then the caller must provide on the next call to ibm,change-msi, one of the following: - - + + - All input parameters the same as the initial call except with the - Sequence Number set to the value in - Next Sequence Number returned from the previous + All input parameters the same as the initial call except with the + Sequence Number set to the value in + Next Sequence Number returned from the previous ibm,change-msi call. - + - All input parameters the same as the initial call except with - Function set to 2 and the + All input parameters the same as the initial call except with + Function set to 2 and the Sequence Number set to 1, if the caller is wanting to - abort the previously started + abort the previously started ibm,change-msi operation. - + - + - R1-R1--9. - For the MSI option: If the + For the MSI option: If the ibm,change-msi RTAS call returns something other than - 0 for the - Final Number of Interrupts, then the + 0 for the + Final Number of Interrupts, then the ibm,query-interrupt-source-number RTAS call must be - used to get the current interrupt source numbers, even if the + used to get the current interrupt source numbers, even if the ibm,change-msi call has returned the same number of interrupts as before the call. - + - R1-R1--10. - For the MSI option: Firmware must not return a - Status of -2 or 990x when the - Requested Number of Interrupts is set to 0 or for - Function 0 (query only) or for + For the MSI option: Firmware must not return a + Status of -2 or 990x when the + Requested Number of Interrupts is set to 0 or for + Function 0 (query only) or for Function 2 (set back to default number). - + - R1-R1--11. - For the MSI option: When the + For the MSI option: When the set-indicator RTAS call is made to isolate an IOA (for both DLPAR and PCI Hot Plug operations), the platform must release - any additional MSI numbers that were obtained through the + any additional MSI numbers that were obtained through the ibm,change-msi RTAS call and make them available for use by other ibm,change-msi calls. - + - R1-R1--12. For the MSI option: An OS or device driver that is - calling + calling ibm,change-msi for the purpose of changing the number or type of interrupts for the IOA function must assure that the IOA function cannot be actively performing operations that will generate @@ -11784,9 +11791,9 @@ interrupts. - + - R1-R1--13. For the MSI option: The platform must restore the @@ -11798,70 +11805,70 @@ - + Software Implementation Notes: - - + + Interrupt source numbers for MSIs are not necessarily be assigned contiguously. - + - MSIs and MSI source numbers are not shared (see Requirement + MSIs and MSI source numbers are not shared (see Requirement ). - + - For a multi-function IOA, the + For a multi-function IOA, the ibm,change-msi call is called for each function for which the number of MSIs is to be changed. - + - 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,change-msi again. However, software may issue the - + ibm,change-msi call again either earlier or later than this. - + During a sequence of calls which return -2 or 990x, software may - abort at any time by setting the - Function equal to 2 and the + abort at any time by setting the + Function equal to 2 and the Sequence Number to 1. - + When there is a non-zero number of MSI or MSI-X interrupts assigned, and when software attempts to change the type of interrupts (MSI to MSI-X interrupt or MSI-X to MSI) at the same time as changing the number of interrupts, the platform may return the same number of interrupts as previously assigned, even though a greater number is - available. In this case a second call to + available. In this case a second call to ibm,change-msi to increase the number of interrupts may produce a greater number of interrupts. - + - The platform will return a status -2 or 990x only when the OS - indicates support. The OS indicates support via ibm,client-architecture-support, - vector 4. See section on "Root Node Methods" + The platform will return a status -2 or 990x only when the OS + indicates support. The OS indicates support via ibm,client-architecture-support, + vector 4. See section on "Root Node Methods" for more information. - - + +
- +
<emphasis>ibm,query-interrupt-source-number</emphasis> - The + The ibm,query-interrupt-source-number RTAS call is used to query the interrupt source number and type (level sensitive for LSIs, edge triggered for MSIs) for a specific PCI IOA function’s @@ -11871,26 +11878,26 @@ config_addr) and function interrupt number. This call is issued once for each interrupt of each IOA function, in order to obtain the interrupt source number and type for that interrupt. For - example, if the + example, if the ibm,change-msi RTAS call has previously returned a value of “n” interrupts for the IOA function, then the call is made “n” times for that function (with a relative interrupt number of 0 to n-1). - + - R1-R1--1. - For the MSI option: The platform must implement the + For the MSI option: The platform must implement the ibm,query-interrupt-source-number RTAS call using the - argument call buffer defined by + argument call buffer defined by .   - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,query-interrupt-source-number</emphasis> @@ -11926,7 +11933,7 @@ - Token for + Token for ibm,query-interrupt-source-number @@ -11969,7 +11976,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 @@ -11981,7 +11988,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 @@ -12011,7 +12018,7 @@ -1: Hardware error 0: Success 1: No interrupt assigned for the given PCI configuration - address and + address and IOA Function Interrupt Number. @@ -12023,10 +12030,10 @@ The interrupt source number corresponding to the PCI - configuration address and - IOA Function Interrupt Number, when a + configuration address and + IOA Function Interrupt Number, when a Status of 0 is returned. Undefined for - other + other Status values . @@ -12039,10 +12046,10 @@ The interrupt source trigger corresponding to the PCI - configuration address and - IOA Function Interrupt Number, when a + configuration address and + IOA Function Interrupt Number, when a Status of 0 is returned. Undefined for - other + other Status values . 0: Level sensitive @@ -12054,125 +12061,125 @@
- + - R1-R1--2. For the MSI option: The interrupt source numbers - returned by the + returned by the ibm,query-interrupt-source-number RTAS call must be - the numbers used to control the interrupt as in the - ibm,get-xive, - ibm,set-xive, - ibm,int-on, and + the numbers used to control the interrupt as in the + ibm,get-xive, + ibm,set-xive, + ibm,int-on, and ibm,int-off RTAS calls. - + - R1-R1--2. - For the MSI option: The + For the MSI option: The ibm,query-interrupt-source-number RTAS call must - return a + return a Status of 1 (no interrupt assigned) if the inputs specify a valid PCI configuration address and the PCI configuration - address does not have an interrupt assigned for the specified + address does not have an interrupt assigned for the specified IOA Function Interrupt Number. - + Software and Firmware Implementation Note: Software - may use the - ibm,query-interrupt-source-number RTAS call for all + may use the + ibm,query-interrupt-source-number RTAS call for all IOA Function Interrupt Number values starting at 0 - until a - Status of 1 is returned, rather than using - ibm,change-msi Function 0 (query). That is, the + until a + Status of 1 is returned, rather than using + ibm,change-msi Function 0 (query). That is, the ibm,query-interrupt-source-number RTAS call works - even when the + even when the “ibm,req#msi” property does not exist for the IOA (that is even when the IOA is not requesting one or more MSIs), This might be desirable, for example, if software never plans on using the capability to change the number of MSIs, and therefore does not have - any other use for the + any other use for the ibm,change-msi call.
- +
Enhanced I/O Error Handling (EEH) Option Functions The EEH option requires several additional RTAS calls. In addition, the Error Injection option RTAS calls are required to be implemented, in order to be able to test device driver code that implements recovery based on the EEH option. - See also, + See also, , for additional information about implementing EEH error recovery. - R1-R1--1. For the EEH option: The IOA bus error injection function of the Error Injection option RTAS call must be implemented - concurrently with the EEH option (that is, the - ioa-bus-error token must exist in the + concurrently with the EEH option (that is, the + ioa-bus-error token must exist in the “ibm,errinjct-tokens” property). - + - R1-R1--2. For the EEH option: If the EEH option is implemented for the specified PE configuration address, then calls to the - - ibm,set-eeh-option, ibm,set-slot-reset, and - ibm,slot-error-detail RTAS calls must be governed by + + ibm,set-eeh-option, ibm,set-slot-reset, and + ibm,slot-error-detail RTAS calls must be governed by , otherwise if one of the - invalid transitions in - is attempted, then return a - Status as defined by + invalid transitions in + is attempted, then return a + Status as defined by . - + - R1-R1--3. If the EEH option is not implemented for - the specified PE configuration address and a call is made to one of the - ibm,set-eeh-option, ibm,set-slot-reset, or - ibm,slot-error-detail RTAS calls, then return a + the specified PE configuration address and a call is made to one of the + ibm,set-eeh-option, ibm,set-slot-reset, or + ibm,slot-error-detail RTAS calls, then return a Status of -3 (parameter error). - Software Implementation Note: Some transitions in + Software Implementation Note: Some transitions in are made asynchronously to the OS by the platform (in exceptional cases; see table for details). If - software receives a + software receives a Status of -7 (Unexpected state change) on an RTAS - call which is attempting to change state in + call which is attempting to change state in , then software should read the - state again via the + state again via the ibm,read-slot-reset-state2 RTAS call, in order to obtain the current state. Some legacy implementations may return a -1 instead of a -7. - + - R1-R1--4. For the EEH option: @@ -12180,95 +12187,95 @@ activates the reset to a PE (for example, as part of a recovery action above the PE), including the case where the platform has temporarily deactivated and then reactivated the reset, then the platform must hide - such PE state transition(s) from the OS by returning a - Status of 5 (PE is unavailable) with + such PE state transition(s) from the OS by returning a + Status of 5 (PE is unavailable) with PE Unavailable Info indicating a non-zero value - (temporarily unavailable) for the + (temporarily unavailable) for the ibm,read-slot-reset-state2 RTAS call, until which time the required minimum reset active hold time for the hardware within the PE has been met. Software Implementation Note: Relative to the platform automatically resetting the PE as part of error recovery, as - mentioned in Requirement - , the - PE Recovery Info output of the + mentioned in Requirement + , the + PE Recovery Info output of the ibm,read-slot-reset-state2 RTAS call is provided to enable the software to determine that such a reset has occurred. - + - R1-R1--5. For the EEH option: If the platform deactivates the reset to a PE, except in the case where the OS has - instructed it to do so with the + instructed it to do so with the ibm,set-slot-reset Function 0, then the platform must do all the following: - - + + Hide such a deactivation from the OS during the time that the PE - reset is deactivated by returning a - Status of 5 (PE is unavailable) with + reset is deactivated by returning a + Status of 5 (PE is unavailable) with PE Unavailable Info indicating a non-zero value - (temporarily unavailable) for the + (temporarily unavailable) for the ibm,read-slot-reset-state2 RTAS call. - + Force OS MMIO accesses to the PE during the deactivation time to look like the PE is reset. - + Prevent the PE from introducing errors into the system (for example, from DMA or due to the reset being deactivated prior to the proper active hold time). - + Reactivate the reset, hiding the reset active hold time as - required by Requirement + required by Requirement , or force the PE into the - permanently unavailable state (return a - Status of 5 (PE is unavailable) with - PE Unavailable Info indicating a zero value for the + permanently unavailable state (return a + Status of 5 (PE is unavailable) with + PE Unavailable Info indicating a zero value for the ibm,read-slot-reset-state2 RTAS call). - + - + - R1-R1--6. For the EEH option: The Bridged-I/O EEH option must be implemented concurrently with the EEH option. - + - R1-R1--7. For the EEH option: The 64 bit IOA bus error injection function of the Error Injection option RTAS call must be - implemented concurrently with the EEH option (that is, the - ioa-bus-error-64 token must exist in the + implemented concurrently with the EEH option (that is, the + ioa-bus-error-64 token must exist in the “ibm,errinjct-tokens” property). - + - R1-R1--8. - For the EEH option: The platform must implement the + For the EEH option: The platform must implement the ibm,configure-pe RTAS call. @@ -12291,7 +12298,7 @@ Initial PE State - The state as would be returned from + The state as would be returned from ibm,read-slot-reset-state2, when no asynchronous platform transition has occurred. @@ -12317,39 +12324,39 @@ Load/ Store Allowed - Load/ Store allowed means - the Loads or Stores channel is - open to the PE, and not necessarily that the PE itself has its MMIO space - enabled. The components within the PE also contain enable/disable bits - (for example, the PCI configuration space Memory Space and IO Space + Load/ Store allowed means + the Loads or Stores channel is + open to the PE, and not necessarily that the PE itself has its MMIO space + enabled. The components within the PE also contain enable/disable bits + (for example, the PCI configuration space Memory Space and IO Space enable bits in the PCI header Device Control register). DMA Allowed - DMA allowed means the DMA channel is open to the PE, if the PE - itself has its DMA enabled. The components within the PE also contain - enable/disable bits (for example, the PCI configuration space Bus Master + DMA allowed means the DMA channel is open to the PE, if the PE + itself has its DMA enabled. The components within the PE also contain + enable/disable bits (for example, the PCI configuration space Bus Master enable bit in the PCI header Device Control register). (Normal Operations) - + 1 Reset - Reset may mean that the PE is being held in the reset state by - a reset signal or Hot Reset (PCI Express), or that it may have been - put into this state by the platform via a PCI Express Function Level - Reset (FLR) in response to the ibm,set-slot-reset - RTAS call. In the case of FLR, the platform makes the pulse of the FLR - look like the Hot Reset case to the OS in terms of the Reset state - (See for more information). - Note that the platform does not monitor writes to the FLR bit of an - IOA, and so OS or Device Driver writes directly to the FLR bit on an - IOA will not affect the PE State as shown in + Reset may mean that the PE is being held in the reset state by + a reset signal or Hot Reset (PCI Express), or that it may have been + put into this state by the platform via a PCI Express Function Level + Reset (FLR) in response to the ibm,set-slot-reset + RTAS call. In the case of FLR, the platform makes the pulse of the FLR + look like the Hot Reset case to the OS in terms of the Reset state + (See for more information). + Note that the platform does not monitor writes to the FLR bit of an + IOA, and so OS or Device Driver writes directly to the FLR bit on an + IOA will not affect the PE State as shown in . @@ -12357,15 +12364,15 @@ Load/ Store Disabled - Load/ Store disabled - means that either the PE is in the MMIO Stopped state or that the PE + Load/ Store disabled + means that either the PE is in the MMIO Stopped state or that the PE is reset, the latter giving the appearance of being MMIO Stopped. DMA Disabled DMA disabled means that either the PE is in the DMA - Stopped state or that the PE is reset, the latter giving + Stopped state or that the PE is reset, the latter giving the appearance of being DMA Stopped. @@ -12375,10 +12382,10 @@ 2 Not Reset - Although the current state is “Not Reset”, - the PE may have been reset by the platform in the process of - getting to this state. The PE Recovery Info - output of the ibm,read-slot-reset-state2 + Although the current state is “Not Reset”, + the PE may have been reset by the platform in the process of + getting to this state. The PE Recovery Info + output of the ibm,read-slot-reset-state2 RTAS call will indicate if the platform has done such a reset. @@ -12395,7 +12402,7 @@ - + 4 Not Reset @@ -12408,30 +12415,30 @@ - + 5 Temporarily Unavailable Temporarily unavailable is signaled by a non-zero value r - eturned in the PE Unavailable Info of the + eturned in the PE Unavailable Info of the ibm,read-slot-reset-state2 RTAS calls. - + 5 Permanently Unavailable - Permanently unavailable is signaled by a zero value - returned in the PE Unavailable Info + Permanently unavailable is signaled by a zero value + returned in the PE Unavailable Info of the ibm,read-slot-reset-state2 RTAS calls. - + @@ -12723,44 +12730,44 @@ depicts the four main functions for controlling a PE’s state: - - + + ibm,set-eeh-option Function 2 for releasing a PE from the MMIO Stopped State, when the PE is in State 2 (MMIO Stopped State and DMA Stopped State both active). - + ibm,set-eeh-option Function 3 for releasing a PE from the DMA Stopped State, when the PE is in State 3 (MMIO Stopped State not active and DMA Stopped State active). - + ibm,set-slot-reset Function 0 for releasing a PE’s reset. - + ibm,set-slot-reset Function 1for activating a PE’s reset. - - + + Implementation Note: In the last two bullets, above, for the case of the platform’s use of FLR for resetting the PE, the meaning of “activating” and “deactivating” the PE’s reset has slightly different meaning, but the platform makes - the EEH recovery model transparent. See + the EEH recovery model transparent. See for more details. is a summary of the expected - results of the above four operations. The -7 + results of the above four operations. The -7 Status returns generally will occur for the cases where the PE state has been changed asynchronously to the OS by the - platform. In these cases, software should read the state again (via the + platform. In these cases, software should read the state again (via the ibm,read-slot-reset-state2 RTAS call) in order to determine the current hardware state. @@ -12792,7 +12799,7 @@ Initial PE State - The state as would be returned from + The state as would be returned from ibm,read-slot-reset-state2, when no asynchronous platform transition has occurred. @@ -12801,7 +12808,7 @@ - + 0 Not Reset @@ -12809,39 +12816,39 @@ Load/ Store Allowed - Load/ Store allowed means - the Loads or Stores channel is - open to the PE, and not necessarily that the PE itself has its MMIO space - enabled. The components within the PE also contain enable/disable bits - (for example, the PCI configuration space Memory Space and IO Space + Load/ Store allowed means + the Loads or Stores channel is + open to the PE, and not necessarily that the PE itself has its MMIO space + enabled. The components within the PE also contain enable/disable bits + (for example, the PCI configuration space Memory Space and IO Space enable bits in the PCI header Device Control register). DMA Allowed - DMA allowed means the DMA channel is open to the PE, if the PE - itself has its DMA enabled. The components within the PE also contain - enable/disable bits (for example, the PCI configuration space Bus Master + DMA allowed means the DMA channel is open to the PE, if the PE + itself has its DMA enabled. The components within the PE also contain + enable/disable bits (for example, the PCI configuration space Bus Master enable bit in the PCI header Device Control register). (Normal Operations) - + 1 Reset - Reset may mean that the PE is being held in the reset state by - a reset signal or Hot Reset (PCI Express), or that it may have been - put into this state by the platform via a PCI Express Function Level - Reset (FLR) in response to the ibm,set-slot-reset - RTAS call. In the case of FLR, the platform makes the pulse of the FLR - look like the Hot Reset case to the OS in terms of the Reset state - (See for more information). - Note that the platform does not monitor writes to the FLR bit of an - IOA, and so OS or Device Driver writes directly to the FLR bit on an - IOA will not affect the PE State as shown in + Reset may mean that the PE is being held in the reset state by + a reset signal or Hot Reset (PCI Express), or that it may have been + put into this state by the platform via a PCI Express Function Level + Reset (FLR) in response to the ibm,set-slot-reset + RTAS call. In the case of FLR, the platform makes the pulse of the FLR + look like the Hot Reset case to the OS in terms of the Reset state + (See for more information). + Note that the platform does not monitor writes to the FLR bit of an + IOA, and so OS or Device Driver writes directly to the FLR bit on an + IOA will not affect the PE State as shown in . @@ -12849,15 +12856,15 @@ Load/ Store Disabled - Load/ Store disabled - means that either the PE is in the MMIO Stopped state or that the PE + Load/ Store disabled + means that either the PE is in the MMIO Stopped state or that the PE is reset, the latter giving the appearance of being MMIO Stopped. DMA Disabled DMA disabled means that either the PE is in the DMA - Stopped state or that the PE is reset, the latter giving + Stopped state or that the PE is reset, the latter giving the appearance of being DMA Stopped. @@ -12875,7 +12882,7 @@ DMA Disabled - + 4 Not Reset @@ -12890,25 +12897,25 @@ - + 5 Temporarily Unavailable - Temporarily unavailable is signaled by a non-zero value - returned in the PE Unavailable Info of the + Temporarily unavailable is signaled by a non-zero value + returned in the PE Unavailable Info of the ibm,read-slot-reset-state2 RTAS calls. - + 5 Permanently Unavailable - Permanently unavailable is signaled by a zero value - returned in the PE Unavailable Info + Permanently unavailable is signaled by a zero value + returned in the PE Unavailable Info of the ibm,read-slot-reset-state2 RTAS calls. @@ -12957,7 +12964,7 @@ Status - A + A Status of -3 is returned instead of 0 or -7 if an invalid PCI configuration address is used. An invalid PCI configuration address is generally one which is @@ -12967,7 +12974,7 @@ requirements defined by this architecture. Also, some legacy implementations may return a -1 or -3 instead of a -7, but all implementations are required to implement the - -7 + -7 Status, where appropriate. @@ -13065,7 +13072,7 @@ “deactivate” of the reset has a different meaning than for the Hot Reset case. For FLR, the platform makes the pulse of the FLR look like the Hot Reset case to the OS in - terms of the Reset state (See + terms of the Reset state (See for more information). @@ -13104,7 +13111,7 @@ - + @@ -13163,19 +13170,19 @@ Status - , + , - For - Function 3, if - Function 3 is not implemented, then a - Status of -3 is returned. For + For + Function 3, if + Function 3 is not implemented, then a + Status of -3 is returned. For Function 3, if implemented in the RTAS call, but not implemented for the specified PCI - configuration address, then a + configuration address, then a Status of -8 is returned. In either of - these cases, the PE state is not changed. If + these cases, the PE state is not changed. If Function 3 is implemented, then the - platform indicates this by the + platform indicates this by the “ibm,reset-capabilities” property in the OF device tree. @@ -13209,37 +13216,37 @@ PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) for the domain is the PCI configuration address for the PE primary bus and is the same format as used for the ibm,read-pci-config and - ibm,write-pci-config calls (see Requirement + ibm,write-pci-config calls (see Requirement ), except that the Register field is set to 0. The PE configuration address is obtained as indicated - in + in . - +
<emphasis>ibm,set-eeh-option</emphasis> - + This call is used to enable and disable the EEH domain of a PE, to - remove a PE from the MMIO Stopped state to continue - Load and + remove a PE from the MMIO Stopped state to continue + Load and Store operations to the domain, and to remove a PE from the DMA Stopped state to continue DMA operations to the domain. The PE configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the PE is obtained as defined in + for the PE is obtained as defined in . - + - R1-R1--1. - For the EEH option: RTAS must implement an + For the EEH option: RTAS must implement an ibm,set-eeh-option call - using the argument call buffer defined by + using the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,set-eeh-option</emphasis> @@ -13275,7 +13282,7 @@ - Token for + Token for ibm,set-eeh-option @@ -13318,7 +13325,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 @@ -13330,7 +13337,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 @@ -13344,7 +13351,7 @@ 0: Disable EEH option for the PE (no-op for PEs with PCI Express IOAs) 1: Enable EEH option for the PE - 2: Release the PE for + 2: Release the PE for Load/ Store operations 3: Release the PE for DMA operations @@ -13373,57 +13380,57 @@
Software and Platform Implementation Note: For - platforms that enable EEH by default, + platforms that enable EEH by default, ibm,set-eeh-option Function 0 (disable EEH) is a - no-op. However, + no-op. However, ibm,set-eeh-option Function 1 (enable EEH) is still required as a signalling method from the device driver to the platform - that the device driver is at least EEH aware (see Requirement + that the device driver is at least EEH aware (see Requirement ). - + - R1-R1--2. - For the EEH option: Software must use the + For the EEH option: Software must use the ibm,get-config-addr-info2 RTAS call, when supported, - to get the EEH domain span of the PE, otherwise software must use the + to get the EEH domain span of the PE, otherwise software must use the ibm,read-slot-reset-state2 RTAS call in order to - determine the span, and then software should attempt to perform all + determine the span, and then software should attempt to perform all ibm,set-slot-reset and - + ibm,set-eeh-option RTAS calls appropriately, based on the EEH - capabilities and as governed by + capabilities and as governed by . - + - R1-R1--3. For the EEH option: If the EEH option is implemented for the specified PE configuration address, on a call to the - + ibm,set-eeh-option with a - + Function of 0 (disable EEH) the platform must do one of the following: - - + + If any IOA in the PE is enabled (if any of the Bus Master, Memory Space or I/O Space bits in the Command Register of the IOA’s - configuration space are 1), then do nothing and return a + configuration space are 1), then do nothing and return a Status of 0 (Success). - + If the platform allows disabling of EEH and the disabling of EEH for the PE violates another requirement relative to LPAR, then the @@ -13431,53 +13438,53 @@ configuration address and must return a -7 (unexpected state change) or a -1 (hardware error), with -7 preferred. - + If the platform allows disabling of EEH and the disabling of EEH for the PE does not violate the other requirements relative to LPAR, then clear the MMIO Stopped State and DMA Stopped State, and disable the EEH option, for the specified PE configuration address. - + If the default for the platform is EEH enabled, then do nothing - and return a + and return a Status of 0 (Success). - + - + - R1-R1--4. For the EEH option: If the OS allows the DMA to be enabled for a PE that is in the DMA Stopped state without - the use of a reset operation (that is, the use of the - ibm,set-eeh-option with a + the use of a reset operation (that is, the use of the + ibm,set-eeh-option with a Function of 3), the device driver must first do all necessary cleanup of its IOA to prevent the IOA from doing anything destructive when it starts DMA again. - + - R1-R1--5. For the EEH option: If a device driver is going to enable EEH and the platform has not defaulted to EEH enabled, then it must do so before it does any operations with its IOA, including any - configuration cycles or - Load or + configuration cycles or + Load or Store operations. - + - R1-R1--6. For the EEH option: If an EEH domain is enabled for a @@ -13494,60 +13501,60 @@ latent errors showing up during the startup phase. - + - R1-R1--7. For the EEH option: If the Slot Level EEH Event - Interrupt option is not implemented for the PE, then return a - Status of -3 if + Interrupt option is not implemented for the PE, then return a + Status of -3 if Function 4 or 5 is attempted. - + - R1-R1--8. For the EEH with the Slot Level EEH Event Interrupt option: Function 4 and 5 must be implemented for all PE under - nodes that contain the + nodes that contain the “ibm,io-events-capable” property. - +
- +
<emphasis>ibm,set-slot-reset</emphasis> - + This call is used to reset a PE. The PE configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the PE is obtained as defined in + for the PE is obtained as defined in . All PEs have the capability of being reset independently. Resets outside or within the PE are not architected, but may be allowed by the platform implementation, providing that it does not violate other requirements of this architecture. The platform may use one of two methods to reset a PCI Express PE, - when the - ibm,set-slot-reset RTAS call is made with the + when the + ibm,set-slot-reset RTAS call is made with the Function 1/ Function 0 (activate the reset/deactivate the reset). - - + + If the PE is a single function of a multi-function IOA, then the Function Level Reset (FLR) option is required to be implemented by the function, and the platform uses FLR to reset the function. When the platform uses FLR instead of Hot Reset to reset a PCI Express PE, the - platform provides the + platform provides the “ibm,pe-reset-is-flr” property in the function’s OF Device Tree node, and provides the same EEH recovery - model to the software, as in the Hot Reset case, and as defined by + model to the software, as in the Hot Reset case, and as defined by . The property is provided in the case where there may be slightly different device-specific reset recoveries by the software for the FLR case. @@ -13555,28 +13562,28 @@ Software Implementation Note: The platform does not monitor writes to the FLR bit of an IOA, and so OS or Device Driver writes directly to the FLR bit on an IOA will not affect the PE State as - shown in + shown in . - + Otherwise, a PCI Express Hot Reset is used. - - + + - R1-R1--1. - For the EEH option: The + For the EEH option: The ibm,set-slot-reset call must be implemented using the - argument call buffer defined by + argument call buffer defined by . - - + + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,set-slot-reset</emphasis> @@ -13612,7 +13619,7 @@ - Token for + Token for ibm,set-slot-reset @@ -13655,7 +13662,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 @@ -13667,7 +13674,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 @@ -13680,7 +13687,7 @@ 0: Deactivate the reset to the PE 1: Activate the reset to the PE (for PCI Express, if the - platform uses FLR to reset the PE, the platform provides the + platform uses FLR to reset the PE, the platform provides the “ibm,pe-reset-is-flr” property in the function’s OF Device Tree node) 3: (optional) Activate the reset to the PE, using a PCI @@ -13710,15 +13717,15 @@
- + - R1-R1--2. For the EEH option: After activation of the reset ( Function 1 or 3), software must delay the deactivation of the reset ( - Function 0) to that PE via the + Function 0) to that PE via the ibm,set-slot-reset call, until the minimum reset signal active time has elapsed, as designated by the bus specifications for the particular type bus or buses involved (100 @@ -13726,37 +13733,37 @@ Software Implementation Notes: - - + + The device driver is responsible for any additional clean up required beyond that provided by a reset to the IOA. For PCI Express, the clean up may be slightly different based on whether the platform used FLR - or Hot Reset to reset the PE. When FLR is used, the platform provides the + or Hot Reset to reset the PE. When FLR is used, the platform provides the “ibm,pe-reset-is-flr” property in the function’s OF Device Tree node. - + - The software is responsible for quiescing (stopping) any MMIO - Load and + The software is responsible for quiescing (stopping) any MMIO + Load and Store activities to the PE prior to resetting the PE. - + If the platform uses FLR to implement the PE reset, software may need to understand that this is a pulse and not a solid level, such that - the adapter is not held at reset during the time from the call with - Function 1 and the call with + the adapter is not held at reset during the time from the call with + Function 1 and the call with Function 0. - + - + - R1-R1--3. For the EEH option: After deactivation of the reset ( @@ -13768,56 +13775,56 @@ Software Implementation Notes: - - + + Different implementations of PCI Express may require different amounts of delay in order to traverse the I/O fabric since individual component delays are plug-in card specific. - + - The ibm,read-slot-reset-state2 RTAS call returns a + The ibm,read-slot-reset-state2 RTAS call returns a PE Reset State of 5 (PE is unavailable) while any reset delay time is happening for hardware outside the PE. - + - + - R1-R1--4. - For the EEH option: If the - ibm,set-slot-reset call is called with a + For the EEH option: If the + ibm,set-slot-reset call is called with a Function of 0 (deactivate) and any reset to the reset - domain specified by the + domain specified by the PE configuration address is active, then the RTAS call must de-activate all resets to that PE configuration address. - + - R1-R1--5. - For the EEH option: If the - ibm,set-slot-reset call is called with a + For the EEH option: If the + ibm,set-slot-reset call is called with a Function of 0 (deactivate) and there is no operation to be performed (for example, the reset to the reset domain specified by the PE configuration address is not active), then the RTAS call must - return a + return a Status of 0 (success). - + - R1-R1--6. - For the EEH option: When the - ibm,set-slot-reset call is called with a + For the EEH option: When the + ibm,set-slot-reset call is called with a Function of 1 or 3 (activate) with a valid PHB Unit ID and config_addr and it is the case that FLR is not being used by the platform to reset the PE, then the RTAS call must activate the reset to @@ -13825,25 +13832,25 @@ already activated. - + - R1-R1--7. - For the EEH option: When the - ibm,set-slot-reset RTAS call implements - Function 3, the platform must also provide the - “ibm,reset-capabilities” property in the + For the EEH option: When the + ibm,set-slot-reset RTAS call implements + Function 3, the platform must also provide the + “ibm,reset-capabilities” property in the RTAS node of the OF device tree. - + - R1-R1--8. - For the EEH option: When the - ibm,set-slot-reset call is called with a + For the EEH option: When the + ibm,set-slot-reset call is called with a Function of 0 (deactivate) with a valid PHB Unit ID and config_addr and if the corresponding PE is in the MMIO Stopped or DMA Stopped state, then the RTAS call must bring that PE as designated by the @@ -13851,71 +13858,71 @@ and clear any applicable platform EEH status state. - + - R1-R1--9. For the EEH option: When the platform uses FLR to reset a PCI Express PE ( - ibm,set-slot-reset call with a - Function of 1(activate) followed by a call with + ibm,set-slot-reset call with a + Function of 1(activate) followed by a call with Function 0 (deactivate)), then the platform must - provide the + provide the “ibm,pe-reset-is-flr” property in the function’s OF Device Tree node, and the platform must always use FLR to reset a PE which contains this property in the OF Device Tree. - + - R1-R1--10. For the EEH option: For a PCI Express PE, the platform must provide the EEH recovery model to the software, as - defined by + defined by , regardless of whether Hot Reset or FLR is used to reset the PE. - +
- +
<emphasis>ibm,read-slot-reset-state2</emphasis> This call queries the state of a PE, and dynamically determines whether a PCI configuration address corresponds to a PE primary bus (that - is, if it is the PE configuration address). In addition, when the + is, if it is the PE configuration address). In addition, when the PE Reset State parameter is a 5 (PE is unavailable), - then the + then the PE Unavailable Info indicates an approximate amount of time for which the PE might be unavailable. The PE configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the PE is obtained as defined in + for the PE is obtained as defined in . - When the + When the ibm,get-config-addr-info2 RTAS call is implemented, that call can be used instead of this one to determine the PE - configuration address. See - and + configuration address. See + and . - + - R1-R1--1. ibm,read-slot-reset-state2 call - must be implemented using the argument call buffer defined by + must be implemented using the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,read-slot-reset-state2</emphasis> @@ -13951,7 +13958,7 @@ - Token for + Token for ibm,read-slot-reset-state2 (see Firmware Implementation note, below) @@ -13974,10 +13981,10 @@ 4: Always allowed. - 5: May be allowed, depending on the value of the + 5: May be allowed, depending on the value of the “ibm,read-slot-reset-state-functions” property - in the + in the RTAS node of the device tree ( ). @@ -14001,7 +14008,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 @@ -14013,7 +14020,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 @@ -14038,22 +14045,22 @@ - Except for a + Except for a PE Reset State of 5, this output is not - valid unless the + valid unless the Config_addr Capabilities output is a 1 and - the + the Status is a 0. 0: Reset deactivated and the PE is not in the MMIO Stopped or DMA Stopped state 1: Reset activated and the PE is not in the MMIO Stopped or DMA Stopped states 2: The PE is in the MMIO Stopped and DMA Stopped states - with the reset deactivated and the + with the reset deactivated and the Load/ Store path is disabled 4: The PE is in the DMA Stopped state with the reset - deactivated and the + deactivated and the Load/ Store path is enabled 5: PE is unavailable @@ -14066,11 +14073,11 @@ - This output is not valid if the + This output is not valid if the PE Reset State is a 5. - 0: EEH not supported for the + 0: EEH not supported for the Config_addr - 1: EEH supported for the + 1: EEH supported for the Config_addr @@ -14081,10 +14088,10 @@ - This output is not valid unless the + This output is not valid unless the Config_addr Capabilities output is a 1 and - the - PE Reset State is a 5 and the + the + PE Reset State is a 5 and the Status is a 0, in which case the value of this parameter is a 0 if the PE is permanently unavailable, and non-zero if a recovery is in progress and there is an expected @@ -14098,13 +14105,13 @@ PE Recovery Info - This output is only valid if the + This output is only valid if the “ibm,read-slot-reset-state-functions” property - in the + in the RTAS node of the device tree indicates that - it is implemented and the call is made with a - Number Outputs of at least 5 and the + it is implemented and the call is made with a + Number Outputs of at least 5 and the PE Reset State is a value of 2. This is a 32-bit field with bit significance, as follows:   @@ -14129,48 +14136,48 @@ PE.   Bit 30 - Retry Count Hint - Bit 30 = 0: Either the PE associated with the + Bit 30 = 0: Either the PE associated with the Config_addr was the source of this PE - entering the + entering the PE Reset State of 2, or the platform has not determined whether this PE was the source or not. Bit 30 = 1: The platform has determined that the PE - associated with the + associated with the Config_addr was not the source of this PE - entering the + entering the PE Reset State of 2. That is, setting this - bit indicates that this PE entered the + bit indicates that this PE entered the PE Reset State of 2 as a side-effect of some error outside of this PE’s domain. Software may use - this hint to not count this occurrence of the + this hint to not count this occurrence of the PE Reset State of 2 as part of any EEH error recovery retry count that it might be keeping for this PE.   Bit 31 - Reset Status Bit 31 = 0: PE was not reset as a result of the platform - transition to + transition to PE Reset State of 2. Bit 31 = 1: PE was reset as a result of the platform - transition to + transition to PE Reset State of 2. If the PE is not below - a node marked with the special value of the - “status” property of + a node marked with the special value of the + “status” property of “reserved”, then after deactivation of the platform-initiated PE reset, the platform is required to delay access to that PE until the minimum time after reset that is required for the PE to be come stable has elapsed, as designated by the bus specifications for the particular type bus or buses involved (for example, 1.5 seconds - for PCI Express), by returning - PE Reset State of 5 with + for PCI Express), by returning + PE Reset State of 5 with PE Unavailability Info non-zero (temporarily unavailable) until that time has elapsed). If the - PE is below a node marked with the special value of the - “status” property of + PE is below a node marked with the special value of the + “status” property of “reserved”, then after deactivation of the platform-initiated PE reset, the firmware - immediately (without delay) transitions the PE to the + immediately (without delay) transitions the PE to the PE Reset State of 2, and it is the controlling software that is required to do the bus-specific delays. @@ -14182,11 +14189,11 @@ Firmware Implementation Note: The argument call buffer structure and requirements for this call are the same as for the - old (removed from this architecture) + old (removed from this architecture) ibm,read-slot-reset-state call, except for the last output parameter. Therefore, it is possible for platforms that still - require the old - ibm,read-slot-reset-state RTAS call to implement the + require the old + ibm,read-slot-reset-state RTAS call to implement the ibm,read-slot-reset-state and ibm,read-slot-reset-state2 calls with the same RTAS token and use the number of output parameters to determine whether or not @@ -14195,168 +14202,168 @@ Platform Implementation Notes: - - + + - The ibm,read-slot-reset-state2 RTAS call only returns a + The ibm,read-slot-reset-state2 RTAS call only returns a PE Reset State of 1 (Reset activated and the PE is not in the MMIO Stopped or DMA Stopped state) when the reset may be removed by software; that is, if the error is potentially recoverable. If the firmware has detected a hardware error that is such that the reset to - the device cannot be removed or is not safe to remove, the - ibm,read-slot-reset-state2 does not return a - PE Reset State of 1, but instead returns a + the device cannot be removed or is not safe to remove, the + ibm,read-slot-reset-state2 does not return a + PE Reset State of 1, but instead returns a PE Reset State of 5 (PE is unavailable) along with PE Unavailable Info of 0 (PE is permanently unavailable). - + The ibm,read-slot-reset-state2 RTAS call should never - return a -1 (hardware error), but should instead return a - PE Reset State of 5 (PE is unavailable) with a + return a -1 (hardware error), but should instead return a + PE Reset State of 5 (PE is unavailable) with a PE Unavailable Info of 0 (PE is permanently unavailable). - + - + - R1-R1--2. - The ibm,read-slot-reset-state2 RTAS call must return a + The ibm,read-slot-reset-state2 RTAS call must return a Reset State value of 5 (PE is unavailable) under any of the following conditions: - - + + Firmware has determined that communications with the PE is not available or the path to the PE cannot be traversed at the current time - + The ibm,slot-error-detail RTAS call has been called with - a + a Function of 2, and none of the resetting conditions - specified in Requirement + specified in Requirement have been met. - - + + Software Implementation Notes: - - + + - The condition under Requirement + The condition under Requirement may be temporary, with a recovery time in the range of seconds (for example, as little as 3 seconds or up to couple of minutes). Software may chose to delay the time - indicated in the - PE Unavailable Info and issue the + indicated in the + PE Unavailable Info and issue the ibm,read-slot-reset-state2 call again when a temporary condition exists. The condition may also be clearable with a - power cycle of the PE, in which case the firmware may return a - Status of 990x to the + power cycle of the PE, in which case the firmware may return a + Status of 990x to the set-power-level RTAS call, to delay long enough to clear the temporary condition. - + Config_addr Capabilities may be indeterminate when the PE Reset State of 5 (PE is unavailable) is returned. - Software should ignore the - Config_addr Capabilities return when the + Software should ignore the + Config_addr Capabilities return when the PE Reset State of 5 is returned. - + - + - R1-R1--3. - If the - ibm,read-slot-reset-state2 RTAS call must return a + If the + ibm,read-slot-reset-state2 RTAS call must return a PE Reset State value of 5 (PE is unavailable) then it - must indicate in the + must indicate in the PE Unavailable Info parameter one of the following: - - + + A value of zero, if there is no error recovery in progress that makes the PE available in any predictable amount of time (that is, the PE is “permanently” unavailable; for example, until a power cycle or until a repair action). - + A non-zero value, indicating the approximate time in milliseconds after which the path to the PE is expected to become available again. - + - + - R1-R1--4. - The - ibm,read-slot-reset-state2 RTAS call must return a - Config_addr Capabilities of 1 (EEH supported for the - Config_addr) for every + The + ibm,read-slot-reset-state2 RTAS call must return a + Config_addr Capabilities of 1 (EEH supported for the + Config_addr) for every Config_addr within a PE and for the PE configuration address. - + - R1-R1--5. - The + The ibm,read-slot-reset-state2 RTAS call must comply with - the state transitions defined in + the state transitions defined in . - + - +
<emphasis>ibm,get-config-addr-info2</emphasis> - + This call is used obtain information about fabric configuration - addresses, given the PCI configuration address. See + addresses, given the PCI configuration address. See for more information on PEs and determining PE configuration addresses. The PCI configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the call is defined by + for the call is defined by . - + - R1-R1--1. - The + The ibm,get-config-addr-info2 call - must be implemented using the argument call buffer defined by + must be implemented using the argument call buffer defined by . - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,get-config-addr-info2</emphasis> @@ -14392,7 +14399,7 @@ - Token for + Token for ibm,get-config-addr-info2 (see Firmware Implementation note, below) @@ -14436,7 +14443,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 @@ -14448,7 +14455,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 @@ -14459,7 +14466,7 @@ - See + See for available functions. @@ -14485,7 +14492,7 @@ - See + See for values. @@ -14494,18 +14501,18 @@
- + - R1-R1--2. - The - ibm,get-config-addr-info2 RTAS call must return the - Data output as per + The + ibm,get-config-addr-info2 RTAS call must return the + Data output as per . - + - Input and + <title>Input and <emphasis>ibm,get-config-addr-info2 Function</emphasis> <emphasis>Info</emphasis> Output @@ -14542,23 +14549,23 @@ Get PE configuration address - PE configuration address (as defined by + PE configuration address (as defined by ). Result returned in - + Info output is: - Equal to the + Equal to the Config_addr input if there is no bridge or switch between the IOA function (endpoint) and the PE primary bus. - Equal to the + Equal to the Config_addr of the PE primary bus if there is a bridge or switch between the IOA function and the PE primary bus. - Undefined if + Undefined if Config_addr is not in a PE (query for PE - state by using - Function 1 first or by - ibm,read-slot-reset-state2 RTAS call). A + state by using + Function 1 first or by + ibm,read-slot-reset-state2 RTAS call). A Status of -3 (Parameter Error) is returned in this case, also. @@ -14571,9 +14578,9 @@ Query shared PE state - 0: + 0: Config_addr is not in a PE (EEH not - supported for the + supported for the Config_addr). 1: Not shared (Only one IOA function in the PE). 2: Shared (More than one IOA function in the PE). @@ -14585,12 +14592,12 @@ - + - +
<emphasis>ibm,slot-error-detail</emphasis> - + This call combines device driver information, as gathered by the device driver prior to this call, with information derived by firmware from the platforms I/O infrastructure to create a detailed event log @@ -14599,53 +14606,53 @@ event. In addition, the OS can mark a PE configuration address as being in an unavailable state due to excessive errors. The caller supplies the device driver information, referenced by - the - Device_Driver_Error_Buffer argument. The + the + Device_Driver_Error_Buffer argument. The Returned_Error_Buffer argument points to a buffer that this call fills with valid error log data as defined in the error log format section. Different platforms log using different versions of the error logging format. The error log data may include platform - specific data as well as device driver data passed in the + specific data as well as device driver data passed in the Device_Driver_Error_Buffer. Regardless of the error - log version used, the data in the + log version used, the data in the Returned_Error_Buffer is in an extended log format as - defined in + defined in . When the call returns data for version 6 or greater, the device driver error buffer data is included as the last User Data section. The device driver data in the return buffer may be truncated from what is passed by the device driver or completely eliminated as necessary to ensure that the returned buffer length is not exceeded. - The + The Config_addr supplied is the PE configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the PE, obtained as defined in + for the PE, obtained as defined in , or a configuration address within the PE. The I/O fabric information that is captured by the platform consists of useful PCI configuration state at and above the - supplied + supplied Config_addr. This RTAS call supports both plug-in PCI cards and built-in PCI IOAs. In this section, the term unavailable, when applied to a PE, means - that + that ibm,read-slot-reset-state2 would return a PE Reset State of 5 (PE is unavailable) at the current time. - + - R1-R1--1. For the EEH option: The - argument call buffer for the + argument call buffer for the ibm,slot-error-detail call must correspond to the - definition given in + definition given in . - +
- Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,slot-error-detail</emphasis> @@ -14681,7 +14688,7 @@ - Token for + Token for ibm,slot-error-detail @@ -14723,7 +14730,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 @@ -14735,7 +14742,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 @@ -14758,7 +14765,7 @@ - Length of the + Length of the Device_Driver_Error_Buffer @@ -14780,7 +14787,7 @@ - Length of the + Length of the Returned_Error_Buffer @@ -14815,254 +14822,254 @@
- + - R1-R1--2. - The + The Returned_Error_Buffer format must be the same as - implemented by + implemented by event-scan on the platform. - + - R1-R1--3. To prevent standard error log record - truncation, the + truncation, the Returned_Error_Buffer_Length must equal the value of - the OF device tree property + the OF device tree property “rtas-error-log-max”. - + - R1-R1--4. - If the PE corresponding to the + If the PE corresponding to the Config_addr is in the MMIO Stopped or DMA Stopped - state, then the - ibm,slot-error-detail RTAS call must return a + state, then the + ibm,slot-error-detail RTAS call must return a Status of 0 and an error log that defines the FRU or FRUs to which the error is isolated. - + - R1-R1--5. - If the communications with the - Config_addr is not available, the path to the + If the communications with the + Config_addr is not available, the path to the Config_addr cannot be traversed at the current time, - or this call has previously made with a + or this call has previously made with a Function of 2 and none of the conditions that reset - this state have been met (that is the PE is unavailable), then the - ibm,slot-error-detail RTAS call must return a + this state have been met (that is the PE is unavailable), then the + ibm,slot-error-detail RTAS call must return a Status of 0 and an error log that defines the FRU or FRUs to which the error is isolated. - + - R1-R1--6. - If the conditions in Requirements - and - are not met, then the - ibm,slot-error-detail RTAS call must return a + If the conditions in Requirements + and + are not met, then the + ibm,slot-error-detail RTAS call must return a Status of 1, no error found, with no error log entry returned. Software and Platform Implementation Note: In some cases, the platform may return an information-only error log to meet - Requirements - and + Requirements + and . For example, in some implementations this might be appropriate if the actual error was already - logged via another RTAS call or this call was previously made with a + logged via another RTAS call or this call was previously made with a Function of 2 and none of the conditions that reset this state have been met. - + - R1-R1--7. Once a PE is unavailable and in the absence of any state-resetting action by the OS that clears the corresponding PE configuration address EEH error (for example, reset or - power cycle), the platform must return an error log in response to the + power cycle), the platform must return an error log in response to the ibm,slot-error-detail RTAS call. - + - R1-R1--8. Once a PE has experienced a state-resetting action by the OS that clears the corresponding PE configuration address EEH error (for example, reset or power cycle), that - makes the PE available, the platform must return a + makes the PE available, the platform must return a Status of 1, no error found, with no error log entry - in response to the + in response to the ibm,slot-error-detail RTAS call. - + - R1-R1--9. - If the ibm,slot-error-detail RTAS call + If the ibm,slot-error-detail RTAS call Device_Driver_Error_Buffer_Length argument is non-zero, indicating the existence of optional device driver error data, - the referenced buffer must contain an extended event log as defined in + the referenced buffer must contain an extended event log as defined in . - + - R1-R1--10. (Requirement Number Reserved For Compatibility) - + - R1-R1--11. - When the + When the ibm,slot-error-detail RTAS call returns an extended - log debug record in the buffer specified by the + log debug record in the buffer specified by the Returned_Error_Buffer argument as mandated by - Requirements - and + Requirements + and it must truncate the record at - the length specified by the + the length specified by the Returned_Error_Buffer_Length argument. - + - R1-R1--12. - If a Function of 2 is passed to the + If a Function of 2 is passed to the ibm,slot-error-detail RTAS call, RTAS must - unconditionally set the state of the PE corresponding to the + unconditionally set the state of the PE corresponding to the Config_addr to permanently unavailable; that is, any subsequent calls to ibm,read-slot-reset-state2 return a PE Reset State of - 5 (PE is unavailable) with the + 5 (PE is unavailable) with the PE Unavailable Info argument set to zero. - + - R1-R1--13. RTAS must not change a PE Reset state of permanently unavailable unless one of the following occur: - - + + A PCI Hot Plug condition for the slot is encountered (as determined by the power being turned off and then on for the slot) - + The power domain is power cycled for another reason (for example, a power down of the OS image that owns the IOA) - + The state is cleared by a partition reboot or a dynamic LPAR reassignment of the PCI configuration address. - + - + - R1-R1--14. After a PE enters the MMIO and DMA Stopped States due to an error, the platform must keep cached error - information relative to that error, for reporting via the + information relative to that error, for reporting via the ibm,slot-error-detail RTAS call, until any one of the following events occurs: - - + + The ibm,slot-error-detail RTAS call is called and the error information is returned. - + - The reset to the PE is activated via the + The reset to the PE is activated via the ibm,set-slot-reset RTAS call. - + - The removal of the PE from the DMA Stopped State via - Function 3 of the + The removal of the PE from the DMA Stopped State via + Function 3 of the ibm,set-eeh-option RTAS call. - + - The start of a DR operation as signalled by the calling of - set-indicator with + The start of a DR operation as signalled by the calling of + set-indicator with isolation-state set to isolate. - + - + - R1-R1--15. - Prior to calling the + Prior to calling the ibm,slot-error-detail RTAS call, the PE which - includes the + includes the Config_addr must not be in the MMIO Stopped State, if the maximum amount of useful information is to be captured, as defined by - Requirement + Requirement . - + - R1-R1--16. - The firmware implementing the + The firmware implementing the ibm,slot-error-detail is responsible for gathering the PCI fabric configuration space registers, including those at the - specified + specified Config_addr, and also any other non-PCI I/O fabric registers that might be useful for debug purposes (for example, internal PHB registers), with the suggested appropriate minimum set of PCI configuration registers captured for each PCI device being as indicated - in + in . - + Suggested Minimum PCI Configuration Registers to - Capture for + Capture for <emphasis>ibm,slot-error-detail</emphasis> @@ -15411,26 +15418,26 @@
- + - R1-R1--17. - If the + If the ibm,slot-error-detail RTAS call is made with the PE - in the PE state of 2 (as defined by + in the PE state of 2 (as defined by ), then the platform must not remove the PE from that state in order to probe the PCI fabric. - + - R1-R1--18. If the ibm,slot-error-detail RTAS call is made with the PE - in the PE state of 4 (as defined by - ), then the + in the PE state of 4 (as defined by + ), then the ibm,slot-error-detail RTAS call must return with the PE in the PE state of 4, except that if an error occurs in the course of probing the PCI fabric that requires a reset of the PE by the platform, @@ -15439,10 +15446,10 @@ Software and Platform Implementation Notes: - - + + - In Requirement + In Requirement , it is possible, as a part of the firmware probing the fabric, that the PE will transition temporarily to a PE state of 2, in the case where another EEH event occurs as part of @@ -15452,9 +15459,9 @@ of these PE state 4->2->4 events may occur as a result of probing the fabric. - + - In Requirement + In Requirement if an EEH event occurs as a result of probing that fabric that results in a reset of the PE, the returned PE state of 2 does not necessarily need to be checked for by the @@ -15463,18 +15470,18 @@ software can continue on with the recovery phase of the EEH processing, and will eventually hit the same event on further processing. - + - +
- +
Bridged-I/O EEH Support Option - + The Bridged-I/O EEH Support Option provides RTAS calls for restoring the boot time configuration of EEH error domains that contain multiple IOAs or multi-function IOAs (for example, mult-function I/O @@ -15500,35 +15507,35 @@ calls can be made for all EEH recovery events, regardless of the type of I/O present. The PE configuration address ( PHB_Unit_ID_Hi, PHB_Unit_ID_Low, and config_addr) - for the PE is obtained as defined in + for the PE is obtained as defined in . - Software Implementation Note: Neither - ibm,configure-bridge nor + Software Implementation Note: Neither + ibm,configure-bridge nor ibm,configure-pe restores changes to an IOA’s - post boot configuration registers except as made through the + post boot configuration registers except as made through the ibm,change-msi RTAS call (for example, to the point of being able to issue PCI memory space MMIO operations to the IOA, or perform DMA operations from the IOA). It is the software’s responsibility to restore any post boot non interrupt changes it made to the IOA’s PCI configuration space registers after calling one of these two RTAS calls. - +
<emphasis>ibm,configure-bridge</emphasis> - + - R1-R1--1. - For the Bridged-I/O EEH Support option: The + For the Bridged-I/O EEH Support option: The ibm,configure-bridge call - must implement the argument call buffer defined by + must implement the argument call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,configure-bridge</emphasis> @@ -15564,7 +15571,7 @@ - Token for + Token for ibm,configure-bridge @@ -15607,7 +15614,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 @@ -15643,122 +15650,122 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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,configure-bridge again. However, software may - issue the + issue the ibm,configure-bridge call again either earlier or later than this. Firmware Implementation Note: - - + + This call needs to limit the long busy to 9900-9902 with at most - a total of 1/5 second before the + a total of 1/5 second before the ibm,configure-bridge succeeds. Any longer delays may cause subsequent hardware or application failures. - + - For hardware errors, return a + For hardware errors, return a Status of 0 (Success). Hardware errors are subsequently discovered by further accesses to the PE and additional EEH events. - + - + - R1-R1--2. - The caller of + The caller of ibm,configure-bridge must provide the PE configuration address, otherwise the RTAS call returns a -3, “Parameter Error”. - + - R1-R1--3. The ibm,configure-bridge call must set up all the PCI to PCI bridges, PCI Express bridges, and PCI Express switches within the PE, the way they were delivered at boot time with any modifications made to it via RTAS calls after boot, and must do - so with a single sequence of calls to + so with a single sequence of calls to ibm,configure-bridge. - + - R1-R1--4. The ibm,configure-bridge call - must only return a + must only return a Status of 990x if one of the following conditions is true: - - + + The operation was not started. - + Firmware is able to restart the same call for this PE even when - other intervening calls to + other intervening calls to ibm,configure-bridge have occurred (That is, OSs are - not required to serialize calls to + not required to serialize calls to ibm,configure-bridge). - + - + - R1-R1--5. Software must - complete all MMIO operations to the IOAs within a PE prior to calling the + complete all MMIO operations to the IOAs within a PE prior to calling the ibm,configure-bridge RTAS call for a PE and must not issue new MMIO operations to the IOAs within the specified PE until after the RTAS call is complete. - + - R1-R1--6. - On return from the + On return from the ibm,configure-bridge RTAS call, the platform must - have the PE in the same EEH state (as defined by + have the PE in the same EEH state (as defined by ) as when the call was made, except that if an error occurs in the course of probing the PCI fabric that requires a reset of the PE by the platform, then discontinue - probing, return a + probing, return a Status of 0 or 1 (as appropriate), and return the PE in the PE state of 2. - + Software and Platform Implementation Note: - - + + - Given Requirements - and + Given Requirements + and , it is permissible for the platform to temporarily transition the PE from a PE state of 2 to PE state of 4, if the call is made with a PE state of 2 but the hardware @@ -15768,9 +15775,9 @@ the course of probing the PCI fabric that put the PE back into the PE state of 4. - + - In Requirement + In Requirement if an EEH event occurs as a result of probing that fabric that results in a reset of the PE, the returned PE state of 2 does not necessarily need to be checked for by the @@ -15779,45 +15786,45 @@ software can continue on with the recovery phase of the EEH processing, and will eventually hit the same event on further processing. - - + +
- +
<emphasis>ibm,configure-pe</emphasis> - This call has about the same semantics as the + This call has about the same semantics as the ibm,configure-bridge RTAS call, except that it: - - + + Has the additional semantics of bypassing the configuration process if the PE has previously not been reset by the platform as a result of entering the EEH Stopped State. - + Configures all the configurations spaces within the PE, - including those of the endpoint devices within the PE (see Requirement + including those of the endpoint devices within the PE (see Requirement ). - - + + Thus, this RTAS call can be made at the beginning of any EEH processing. - + - R1-R1--1. - For the Bridged-I/O EEH Support option: The + For the Bridged-I/O EEH Support option: The ibm,configure-pe call must implement the argument - call buffer defined by + call buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,configure-pe</emphasis> @@ -15853,7 +15860,7 @@ - Token for + Token for ibm,configure-pe @@ -15896,7 +15903,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 @@ -15932,122 +15939,122 @@
- Software Implementation Note: When the 990x + Software Implementation Note: 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,configure-pe again. However, software may issue - the + the ibm,configure-pe call again either earlier or later than this. Firmware Implementation Note: - - + + This call needs to limit the long busy to 9900-9902 with at most - a total of 1/5 second before the + a total of 1/5 second before the ibm,configure-pe succeeds. Any longer delays may cause subsequent hardware or application failures. - + - For hardware errors, return a + For hardware errors, return a Status of 0 (Success). Hardware errors are subsequently discovered by further accesses to the PE and additional EEH events. - + - + - R1-R1--2. - The caller of + The caller of ibm,configure-pe must provide the PE configuration address, otherwise the RTAS call returns a -3, “Parameter Error”. - + - R1-R1--3. If the specified PE has been configured after the last platform or OS initiated reset to - the specified PE with + the specified PE with ibm,configure-connector, - ibm,configure-bridge, or - ibm,configure-pe, then the call must return with a + ibm,configure-bridge, or + ibm,configure-pe, then the call must return with a Status of 0 (Success) without doing any bridge or switch configuration, otherwise the call must set up the configuration spaces of all the PCI to PCI bridges, PCI Express bridges, PCI Express switches, and endpoint functions within the PE, the way they were delivered at boot time except with all sticky error bits left intact, any changes made by calls to ibm,change-msi retained, and must do so with a - single sequence of calls to + single sequence of calls to ibm,configure-pe. Software Implementation Notes: - - + + The configuration of endpoint functions (the “and endpoint - functions” part) in Requirement + functions” part) in Requirement was added to the architecture - after the firmware without that functionality in the + after the firmware without that functionality in the ibm,configure-pe RTAS call was shipping. Therefore, any device driver that might run legacy implementations needs to be - prepared to restore all endpoint function config spaces, since the + prepared to restore all endpoint function config spaces, since the ibm,configure-pe RTAS call might not. - + The ibm,configure-pe RTAS call does not restore non-interrupts configuration space changes that were made after boot (that is, under direction of the device driver or OS). Therefore, use of - the + the ibm,configure-pe RTAS call does not absolve the device driver or OS from the restoration of non-interrupts the PCI configuration space for changes that were made to the configuration space - after boot (see Requirement + after boot (see Requirement ). - + - + - R1-R1--4. - The ibm,configure-pe call must only return a + The ibm,configure-pe call must only return a Status of 990x if one of the following conditions is true: - - + + The operation was not started. - + Firmware is able to restart the same call for this PE even when - other intervening calls to + other intervening calls to ibm,configure-pe have occurred (That is, OSs are not - required to serialize calls to + required to serialize calls to ibm,configure-pe). - + - + - R1-R1--5. Software must @@ -16057,32 +16064,32 @@ the RTAS call is complete. - + - R1-R1--6. - On return from the + On return from the ibm,configure-pe RTAS call, the platform must have - the PE in the same EEH state (as defined by + the PE in the same EEH state (as defined by ) as when the call was made, except that if an error occurs in the course of probing the PCI fabric that requires a reset of the PE by the platform, then discontinue - probing, return a + probing, return a Status of 0 or 1 (as appropriate), and return the PE in the PE state of 2. - + Software and Platform Implementation Note: - - + + - Given Requirements - and + Given Requirements + and , it is permissible for the platform to temporarily transition the PE from a PE state of 2 to PE state of 4, if the call is made with a PE state of 2 but the hardware @@ -16092,9 +16099,9 @@ the course of probing the PCI fabric that put the PE back into the PE state of 2. - + - In Requirement + In Requirement if an EEH event occurs as a result of probing that fabric that results in a reset of the PE, the returned PE state of 2 does not necessarily need to be checked for by the @@ -16103,15 +16110,15 @@ software can continue on with the recovery phase of the EEH processing, and will eventually hit the same event on further processing. - - + +
- +
Error Injection Option - + The Error Injection option (ERRINJCT) allows testing software to check out the OS’s error paths. This architecture defines the following abstract error categories: @@ -16154,16 +16161,16 @@ - R1-R1--1. - For the ERRINJCT option: RTAS must implement the + For the ERRINJCT option: RTAS must implement the ibm,open-errinjct call - using the argument buffer defined by + using the argument buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,open-errinjct</emphasis> @@ -16199,7 +16206,7 @@ - Token for + Token for ibm,open-errinjct @@ -16233,10 +16240,10 @@ - If + If Status is 0, then use this Open Token for - corresponding - ibm,errinjct and + corresponding + ibm,errinjct and ibm,close-errinjct calls @@ -16260,7 +16267,7 @@
- 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 with the same parameters. However, @@ -16268,51 +16275,51 @@ this. Architecture Note: The output buffer is intentionally - reversed from what it should be, according to Requirement - (that is, + reversed from what it should be, according to Requirement + (that is, Status not first output), due to code that was implemented and shipped as defined, above. - + - R1-R1--2. For the ERRINJCT option: On successful completion of - the + the ibm,open-errinjct call, Firmware must return an Open - Token which uniquely identifies the caller on following - ibm,close-errinjct and + Token which uniquely identifies the caller on following + ibm,close-errinjct and ibm,errinjct calls (Firmware may also need to keep around other information about the caller that uniquely identifies the caller when correlated with the Open Token) and must allocate the - ERRINJCT facilities to this caller until this same user calls + ERRINJCT facilities to this caller until this same user calls ibm,close-errinjct. - + - R1-R1--3. For the ERRINJCT option: If the ERRINJCT facility has - been previously opened, a call to + been previously opened, a call to ibm,open-errinjct call, must return a -4. - + - R1-R1--4. - For the ERRINJCT option: RTAS must implement the + For the ERRINJCT option: RTAS must implement the ibm,close-errinjct call - using the argument buffer defined by + using the argument buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,close-errinjct</emphasis> @@ -16348,7 +16355,7 @@ - Token for + Token for ibm,close-errinjct @@ -16379,7 +16386,7 @@ - Open Token that was returned on the corresponding + Open Token that was returned on the corresponding ibm,open-errinjct calls @@ -16405,7 +16412,7 @@
- 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 with the same parameters. However, @@ -16413,34 +16420,34 @@ this. - + - R1-R1--5. For the ERRINJCT option: If the ERRINJCT facility is - not open or was not previously allocated to the user via an + not open or was not previously allocated to the user via an ibm,open-errinjct call (that is, the Open Token along with any other pertinent data does not correspond with the user that - opened the facility via the - ibm,open-errinjct call), then a call to + opened the facility via the + ibm,open-errinjct call), then a call to ibm,close-errinjct call, must return a -4 and the facility must remain open for use by the user that originally opened the facility. - + - R1-R1--6. - For the ERRINJCT option: RTAS must implement the + For the ERRINJCT option: RTAS must implement the ibm,errinjct call - using the argument buffer defined by + using the argument buffer defined by . - + - Argument Call Buffer + <title>Argument Call Buffer <emphasis>ibm,errinjct</emphasis> @@ -16476,7 +16483,7 @@ - Token for + Token for ibm,errinjct @@ -16508,7 +16515,7 @@ Token for the specific error injection class see - Requirement + Requirement @@ -16519,7 +16526,7 @@ - The Open Token that was returned on the corresponding + The Open Token that was returned on the corresponding ibm,open-errinjct call @@ -16555,7 +16562,7 @@
- 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 with the same parameters. However, @@ -16563,45 +16570,45 @@ this. - + - R1-R1--7. For the ERRINJCT option: If the ERRINJCT facility is - not open or was not previously allocated to the user via an + not open or was not previously allocated to the user via an ibm,open-errinjct call (that is, the Open Token along with any other pertinent data does not correspond with the user that - opened the facility via the - ibm,open-errinjct call), then a call to + opened the facility via the + ibm,open-errinjct call), then a call to ibm,errinjct call, must return a -4 and the facility must remain open for use by the user that originally opened the facility. - + - R1-R1--8. For the ERRINJCT option: - The platform must include the + The platform must include the “ibm,errinjct-tokens” property as defined - below in the - /rtas node (see + below in the + /rtas node (see ) of the OF device tree with a specification for each implemented error injection class. - + - R1-R1--9. For the ERRINJCT option: The errinjct-token-names - must be taken from the list provided in + must be taken from the list provided in . - + Errinjct-token-names @@ -16761,15 +16768,15 @@
- + - R1-R1--10. For the ERRINJCT option: For the errinjct-tokens - implemented RTAS must use the work buffer format specified in + implemented RTAS must use the work buffer format specified in . - + Errinjct Work Buffer Formats @@ -16856,22 +16863,22 @@ injection (a 0 in a bit position masks off the bit, a 1 in the bit position enables the bit to be used in the compare). The third word is the config_addr on the bus which is to receive - the injected error. The fourth word is the + the injected error. The fourth word is the PHB_Unit_ID_Hi of the PHB that corresponds - to the - config_addr. The fifth word is the + to the + config_addr. The fifth word is the PHB_Unit_ID_Low of the PHB that corresponds - to the + to the config_addr. The sixth word defines the specifics of when and what to inject, as follows: - - See + + See for values 0 through 19. 20: (Optional) Disable PCI error injection for the specified bus 21: Obtain current error inject values. When RTAS returns - SUCCESS in the + SUCCESS in the Status field the work buffer field values are populated with the current error injected. @@ -16889,22 +16896,22 @@ position masks off the bit, a 1 in the bit position enables the bit to be used in the compare). The fifth word is the config_addr of an IOA on the bus which is to receive the - injected error. The sixth word is the + injected error. The sixth word is the PHB_Unit_ID_Hi of the PHB that corresponds - to the - config_addr. The seventh word is the + to the + config_addr. The seventh word is the PHB_Unit_ID_Low of the PHB that corresponds - to the + to the config_addr. The eighth word defines the specifics of when and what to inject, as follows: - - See + + See for values 0 through 19. 20: (Optional) Disable PCI error injection for the specified bus 21: Obtain current error inject values. When RTAS returns - SUCCESS in the + SUCCESS in the Status field the work buffer field values are populated with the current error injected. @@ -16996,28 +17003,28 @@ as long as the “nature of error” is “single”. The buffer contents should be the same for a “-start” and corresponding “-end”. While not recommended -end can be - replaced with a call to + replaced with a call to ibm,close-errinjct, but improper cleanup the machine may result, with the machine left in an unknown state. - + - R1-R1--11. - For the ERRINJCT option: If the platform - notifies the OS of a specific CEC error using the machine check interrupt in - response to an + For the ERRINJCT option: If the platform + notifies the OS of a specific CEC error using the machine check interrupt in + response to an ibm,errinjct RTAS call, the platform must do so only when the processor’s MSRRI bit is active, unless said error is fatal or involves accessing a storage location that has itself been corrupted or is accessed through a corrupted SLB entry. - + - R1-R1--12. For the ERRINJCT option with the LPAR @@ -17025,30 +17032,30 @@ its own memory pages. - + - R1-R1--13. For the ERRINJCT option with the LPAR option: Hypervisor RTAS must allow a partition to inject IOA bus errors only if all of the following are true: - - + + The IOA bus is not shared with other partitions. - + The EEH option is implemented and enabled for the bus on which the error injection is requested. - + - + - R1-R1--14. For the ERRINJCT option with the LPAR option: The @@ -17056,9 +17063,9 @@ errinjct calls. - + - R1-R1--15. For the SPLPAR option: The platform must either @@ -17067,46 +17074,46 @@ etc.) as if the hardware error had happened. - + - R1-R1--16. - For the Multi-threading Processor + For the Multi-threading Processor option: All threads on the processor on which the error is injected must be prepared to handle the error. - + - R1-R1--17. For the Error Injection option: The software using - the + the ibm,errinjct call must be prepared to receive a -3 for non-implemented errinjct work buffer formats. - + - R1-R1--18. For the ioa-bus-error and ioa-bus-error-64 - functions of the ERRINJCT option: For each + functions of the ERRINJCT option: For each ibm,errinjct RTAS call invocation, the platform must - inject the error specified in the + inject the error specified in the working buffer at most once. - +
- Semantics for + <title>Semantics for <emphasis>ioa-bus-error</emphasis> - <emphasis>ioa-bus-error</emphasis> Sixth Word and + <emphasis>ioa-bus-error</emphasis> Sixth Word and <emphasis>ioa-bus-error-64</emphasis> Eighth Word Values 0-19 @@ -17165,7 +17172,7 @@ For PHB implementations that do not allow injection of a TLP ECRC error into the request, or for the case where the - injection would be in violation of Requirement + injection would be in violation of Requirement due to the hardware configuration, the platform should emulate the error by setting the appropriate error state in the PHB when EEH is @@ -17389,56 +17396,56 @@ - + Platform Implementation Notes: - - + + Platforms that implement LPAR normally do not allow any partition to be configured to perform platform-specific errinjct calls since they are capable of crashing the entire complex. However, the should provide special hidden overrides for laboratory testing purposes. - - + + Software and Firmware Implementation Notes: - + - When a call to + When a call to ibm,errinjct results in an error injected into a processor, then the error is injected on the same processor as the one - that called the + that called the ibm,errinjct RTAS call, not the processor that called - the - ibm,open-errinjct. The OS could call - ibm,open-errinjct, - ibm,errinjct, and + the + ibm,open-errinjct. The OS could call + ibm,open-errinjct, + ibm,errinjct, and ibm,close-errinjct from three different processors. - + - For usability reasons, the + For usability reasons, the ibm,close-errinjct RTAS call should do a reasonable amount of cleanup; turning off error injection where it can. However, since the ERRINJCT option is intended for internal use (that is, not intended to be productized) and since software is allowed to basically - set unlimited error injections between the calls to - ibm,open-errinjct and + set unlimited error injections between the calls to + ibm,open-errinjct and ibm,close-errinjct, the firmware may vary by implementation as to what is cleaned up and what is not. An example of something that might be very difficult to clean up is injection of memory errors. Something that might be easier is to turn off the error injection in all bridges to which the caller has access. Users of the ERRINJCT option should consult the implementation documentation for a particular - platform to learn about the level of cleanup that is done in the + platform to learn about the level of cleanup that is done in the ibm,close-errinjct call for that implementation. In - the severe case, a reboot may even be necessary after the + the severe case, a reboot may even be necessary after the ibm,close-errinjct in order to clear the error. In other cases it may be possible for the caller to partially disable an error that it has set by setting a benign error (for example, in the PCI @@ -17446,27 +17453,27 @@ previously set to inject an error to an address that will never occur to that IOA). - + Test developers are encouraged not to extensively use the platform-specific option to this function. In general, platform-specific implementation options are not carried forward to new platforms. - - + + - +
Firmware Assisted Non-Maskable Interrupts Option (FWNMI) - + The FWNMI option provides firmware support for System Reset interrupts and platform dependent error recovery for recoverable machine checks. The firmware gets control on a non-maskable interrupt (NMI), analyses the condition, and, if the processor was not running inside the hypervisor, reports its findings to the OS. The OS registers system reset - and machine check handlers by issuing either the - ibm,nmi- register or + and machine check handlers by issuing either the + ibm,nmi- register or ibm,nmi- register-2 RTAS call. In addition, with these calls the OS permanently relinquishes to firmware the Machine State Register’s Machine Check Enable bit, the two hundred fifty six @@ -17478,19 +17485,19 @@ results of the firmware’s analysis and any attempted recovery should the hardware signal a machine check or system reset interrupt. The results of an error analysis are reported via a standard error log - structure as defined in + structure as defined in . The storage containing the error log structure is subsequently released back to firmware use by the OS after it has completed its event handling by the issuance, from the - interrupted processor, of the + interrupted processor, of the ibm,nmi-interlock RTAS call. Multiple processors of the same OS image may experience fatal events at, or about, the same time. The first processor to enter the machine check handling firmware reports the fatal error. Subsequent processors serialize waiting for the - first processor to issue the + first processor to issue the ibm,nmi-interlock call. These subsequent processors report “fatal error previously reported”. If, after the - firmware makes a Machine Check call back, and before the OS issues the + firmware makes a Machine Check call back, and before the OS issues the ibm,nmi-interlock call, the same processor that is currently holding the storage containing the error log structure receives another Machine Check NMI, the firmware has no choice but to declare the @@ -17509,19 +17516,19 @@ the determination of the repair action is delayed, and the firmware reports these determinations asynchronously to handling the machine check. The repair action log is queued in the NVRAM and is reported - either in a subsequent + either in a subsequent event-scan if the OS image remains operational, or on - a subsequent boot. In no case, does the OS call + a subsequent boot. In no case, does the OS call check-exception in its machine check notification routine. - The difference between - ibm,nmi- register and - ibm,nmi- register-2 is that + The difference between + ibm,nmi- register and + ibm,nmi- register-2 is that ibm,nmi- register allocates the error reporting - structure in RTAS space while + structure in RTAS space while ibm,nmi- register-2 places the error reporting - structure in real page 7. New OS designs should use - ibm,nmi- register since support for + structure in real page 7. New OS designs should use + ibm,nmi- register since support for ibm,nmi- register-2 will be terminated at some future date. As with all first level interrupt service routines, the SPRG-2 @@ -17534,9 +17541,9 @@ into a page 7 table of addresses to the start of a per processor RTAS save area (only need a single register saved per processor), and acquires a lock located in page 7 to serialize the use of the RTAS state save area - among potentially competing processors. The MSRME + among potentially competing processors. The MSRME bit then prevents single processor Machine Check - stacking in the interval between the Machine Check call back and the + stacking in the interval between the Machine Check call back and the ibm,nmi-interlock call. LPAR implementations should minimize potential effects to innocent partitions due to Machine Check Interrupts affecting other partitions. @@ -17549,52 +17556,52 @@ - R1-R1--1. All platforms must implement the FWNMI option. - + - R1-R1--2. For the FWNMI option: - The platform must include the + The platform must include the “ibm,nmi-register” - RTAS function property name in the OF + RTAS function property name in the OF /rtas node. - + - R1-R1--3. For the FWNMI option: - The platform must include the + The platform must include the “ibm,nmi-register-2” - RTAS function property name in the OF + RTAS function property name in the OF /rtas node if the platform requires support from interim OS versions. - + - R1-R1--4. - For the FWNMI option: RTAS must implement the - ibm,nmi-register and/or + For the FWNMI option: RTAS must implement the + ibm,nmi-register and/or ibm,nmi-register-2, calls as appropriate per - Requirements - and + Requirements + and using the argument buffer - defined by + defined by . - +
Argument Call Buffer <emphasis>ibm,nmi-register or ibm,nmi-register-2</emphasis> @@ -17632,7 +17639,7 @@ - Token for + Token for ibm,nmi-register or nmi-register-2 @@ -17701,12 +17708,12 @@
- + - R1-R1--5. - For the FWNMI option: Once the + For the FWNMI option: Once the OS has registered for NMI notification, it must not change the contents of the two hundred fifty six (256) bytes of the NMI interrupt vectors at real locations @@ -17714,9 +17721,9 @@ 0x7000. - + - R1-R1--6. For the FWNMI option: @@ -17724,27 +17731,27 @@ address of the registered OS Machine Check and System Reset routines must be in the first 32 MB of the OS’s memory address space. - Software Implementation Note: Requirement + Software Implementation Note: Requirement ensures that the registered OS Machine Check and System Reset routines are within the code’s RMA. - + - R1-R1--7. - For the FWNMI option: If the OS registered with + For the FWNMI option: If the OS registered with ibm,nmi-register, firmware must not store the state of the processor at the time of interrupt in interrupt vectors at locations 0x100 or 0x200 or the memory page starting at real location 0x7000. Firmware may use RTAS space to store such state data. - + - R1-R1--8. For the FWNMI option: Once the OS has registered for @@ -17752,12 +17759,12 @@ Interrupts on all of the OS’s processors. - + - R1-R1--9. - For the FWNMI option: The + For the FWNMI option: The platform firmware, for those intercepted System Reset interrupts which platform policy dictate are to be forwarded to the OS, must invoke the OS registered System Reset @@ -17766,9 +17773,9 @@ Reset. - + - R1-R1--10. For the FWNMI option: Once the OS has registered for @@ -17776,9 +17783,9 @@ Interrupts on all of the OS’s processors. - + - R1-R1--11. or the FWNMI option: The platform must provide a @@ -17786,9 +17793,9 @@ processor in a partition. - + - R1-R1--12. For the FWNMI option: The platform firmware must @@ -17798,9 +17805,9 @@ the OS. - + - R1-R1--13. For the FWNMI option: If the platform firmware, on @@ -17811,45 +17818,45 @@ of the Machine Check except that General Purpose Register (GPR) R3 contains the real address of a 16 byte memory buffer containing the original contents of GPR R3 in the first 8 bytes and the RTAS Error Log - (fixed part) (per + (fixed part) (per ) in the second 8 bytes. - + - R1-R1--14. For the FWNMI option: The maximum time for the platform’s processing of a non-fatal machine check interrupt must - be on the order of that taken by the + be on the order of that taken by the check-exception critical call. - + - R1-R1--15. For the FWNMI option: Once the firmware has reported a “fatal” machine check event to an OS image it must only - report “fatal error previously reported” (see + report “fatal error previously reported” (see ) in response to machine checks on any processor belonging to that image. - + - R1-R1--16. For the FWNMI option: If the platform firmware, on analyzing an intercepted Machine Check Interrupt, determines that the OS may not safely continue using the processor (for example a check stop will certainly result), it must select one of the implementation options - given in + given in . - + Unsafe Processor Recovery Options @@ -17902,7 +17909,7 @@ Mark the processor unsafe, do not return to the OS on that processor and notify the OS to at the next event scan time with a fatal return message. - Note: This action + Note: This action may cause the OS to “hang” due to locks held by the failing processor etc. that may cause a surveillance time out. The NVRAM firmware error log retains a @@ -17917,17 +17924,17 @@
- + - R1-R1--17. - For the FWNMI option: RTAS must implement the + For the FWNMI option: RTAS must implement the ibm,nmi-interlock call using the Argument buffer - defined in + defined in which causes the release of the machine check work and reporting area in page 7. - + Argument Call Buffer <emphasis>ibm,nmi-interlock</emphasis> @@ -17965,7 +17972,7 @@ - Token for + Token for ibm,nmi-interlock @@ -18008,35 +18015,35 @@
- + - R1-R1--18. For the FWNMI option: The - + ibm,nmi-interlock RTAS call must not require serialization with respect to any other RTAS or hypervisor calls. - + - R1-R1--19. For the FWNMI option: The processor receiving the nmi signal must, after it - has processed the buffer pointed to by its R3 register, call the + has processed the buffer pointed to by its R3 register, call the ibm,nmi-interlock RTAS call.
- +
Memory Statistics - + Depending upon the platform configuration, various portions of installed platform memory are in one of several states. Some memory may be mapped out of the address space due to an error in one or more @@ -18055,11 +18062,11 @@ to the calling OS image is obtained through the device tree (potentially modified by post boot dynamic reconfiguration).
- +
System Parameters Option - - The system parameters which are defined are shown in + + The system parameters which are defined are shown in . @@ -18288,7 +18295,7 @@ Remote Power On - (see + (see ) @@ -18310,7 +18317,7 @@ Number of rings until power on - (see + (see ) @@ -18329,7 +18336,7 @@ Snoop sequence string - (see + (see ) @@ -18348,7 +18355,7 @@ Serial snoop enable/disable - (see + (see ) @@ -18369,7 +18376,7 @@ Surveillance enable/disable - (see + (see ) @@ -18390,7 +18397,7 @@ Surveillance time interval in minutes - (see + (see ) @@ -18410,7 +18417,7 @@ Surveillance delay in minutes - (see + (see ) @@ -18598,7 +18605,7 @@ CoD options - See + See . @@ -18616,7 +18623,7 @@ Platform Error Classification - See + See . @@ -18634,7 +18641,7 @@ Firmware Boot Options - See + See . @@ -18675,7 +18682,7 @@ Processor Module Information - See + See . @@ -18750,13 +18757,13 @@ Performance boost modes vector - See + See . - From + From ibm,get-system-parameter the field length - is 96 bytes consisting of 3 32 byte bit vectors. To + is 96 bytes consisting of 3 32 byte bit vectors. To ibm,set-system-parameter the field is a single 32 byte bit vector @@ -18857,7 +18864,7 @@ Firmware Service Expiration Date - This is the date a system's system firmware service warranty + This is the date a system's system firmware service warranty period expires. @@ -18875,7 +18882,7 @@ Firmware Service Entitlement Activation Key - This is the activation key used to set or extend a system's firmware service + This is the activation key used to set or extend a system's firmware service warranty period. @@ -18985,14 +18992,14 @@ Notes: - - + + - These system parameters are defined for the + These system parameters are defined for the ibm,get-system-parameter RTAS call only. An attempt - to set them using the + to set them using the ibm,set-system-parameter RTAS call results in a - return + return Status of -9002 (Setting not allowed/authorized). @@ -19004,7 +19011,7 @@ The format of the SPLPAR string is beyond the scope of this - architecture. See also, + architecture. See also, . @@ -19023,157 +19030,157 @@ 'NVDIMM status change' event notification via RTAS check-exception or the time period is exhausted. - - + + - R1-R1--1. All platforms must support the System Parameters option. - + - R1-R1--2. (Requirement Number Reserved For Compatibility) - + - R1-R1--3. For the System Parameters option: If the length of - the data for a parameter in + the data for a parameter in is less than what is specified - in the requirements for a parameter or if the data value in an + in the requirements for a parameter or if the data value in an ibm,set-system-parameter RTAS call is other than what is allowed by the requirements for the parameter, the platform must return a -9999 indicating a parameter error. - + - R1-R1--4. For the System Parameters option: The default values - defined for parameters sp-sen, sp-sti and sp-sdel in the + defined for parameters sp-sen, sp-sti and sp-sdel in the must apply to the platform - prior to any + prior to any ibm,set-system-parameter RTAS call. - + - R1-R1--5. - For the System Parameters option: The + For the System Parameters option: The ibm,get-system-parameter RTAS call must implement the - argument call buffer defined by - . If the + argument call buffer defined by + . If the ibm,set-system-parameter RTAS call is implemented, it - must use the argument call buffer defined by + must use the argument call buffer defined by . - + - R1-R1--6. For the System Parameters option: If the platform - implements the + implements the ibm,set-system-parameter RTAS call it must also - implement the + implement the ibm,get-system-parameter RTAS call. - + - R1-R1--7. For the System Parameters option: A system parameter, - which is not supported by the system, must return a + which is not supported by the system, must return a Status of -3 (System parameter not supported) from the RTAS call. - + - R1-R1--8. For the System Parameters option: A system parameter - for which access is not authorized, must return a + for which access is not authorized, must return a Status of -9002 (Not authorized) from the RTAS call. - + - R1-R1--9. For the System Parameters option: When a platform - implements a system parameter, it must meet the definition in + implements a system parameter, it must meet the definition in including applicable descriptions and notes. - + - R1-R1--10. - For the System Parameters option: An + For the System Parameters option: An ibm,get-system-parameter RTAS call with a buffer - length of zero (0) must return a + length of zero (0) must return a Status of 0 (success) if the parameter is supported and - authorized, a - Status of -3 if not supported, or a + authorized, a + Status of -3 if not supported, or a Status of-9002 if not authorized. - + - R1-R1--11. - For the System Parameters option: An + For the System Parameters option: An ibm,set-system-parameter RTAS call with a parameter - length of zero (0) must return a + length of zero (0) must return a Status of 0 (success) if the parameter is supported and - authorized, a - Status of -3 if not supported, or a + authorized, a + Status of -3 if not supported, or a Status of -9002 if not authorized. Programming Note: A partition may lose or gain - authority for an - ibm,get-system-parameter or + authority for an + ibm,get-system-parameter or ibm,set-system-parameter call dynamically. For - instance, three consecutive calls with the same parameters could return + instance, three consecutive calls with the same parameters could return Status of success, not authorized, and success. - + - R1-R1--12. - For the System Parameters option: The + For the System Parameters option: The platform must enforce the length of system parameter strings as follows: input strings to ibm,set-system-parameters not to exceed 1024 bytes in length else the @@ -19182,15 +19189,15 @@ bytes. - + - R1-R1--13. For the System Parameter option with the SPLPAR option: The Platform must implement parameter token 20 as - defined in - for + defined in + for ibm,get-system-parameter. Implementation Note: Of course the OS is allowed to @@ -19202,7 +19209,7 @@
<emphasis>ibm,get-system-parameter</emphasis> - +
Argument Call Buffer <emphasis>ibm,get-system-parameter</emphasis> @@ -19240,7 +19247,7 @@ - Token for + Token for ibm,get-system-parameter @@ -19322,7 +19329,7 @@
- The + The ibm,get-system-parameter RTAS call fetches the data for the selected parameter and places it at the address specified in the buffer operand. The first two (2) bytes of the data in the buffer are the @@ -19330,27 +19337,27 @@ length of string data includes the length of the NULL but excludes the length field. If the buffer length is less than the returned data length, the data is truncated at the end of the buffer. The maximum length of the - input parameter data string for + input parameter data string for ibm,set-system-parameter is architecturally limited to 1024 bytes of data and 2 bytes of length, totaling 1026 bytes. The maximum length of the output parameter data string for ibm,get-system-parameter is architecturally limited to 4000 bytes of data and 2 bytes of length, totaling 4002 bytes. The only currently valid - parameters are as specified in + parameters are as specified in . - 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-system-parameter with the same parameter - index. However, software may issue the + index. However, software may issue the ibm,get-system-parameter call again either earlier or later than this.
- +
<emphasis>ibm,set-system-parameter</emphasis> - + Argument Call Buffer <emphasis>ibm,set-system-parameter</emphasis> @@ -19388,7 +19395,7 @@ - Token for + Token for ibm,set-system-parameter @@ -19460,29 +19467,29 @@
- The + The ibm,set-system-parameter RTAS call fetches the data from the address specified in the buffer operand and sets it into the - system parameter specified by the + system parameter specified by the Parameter operand. The first two (2) bytes of the data in the buffer are the length of the data, not counting these first two (2) bytes. The length of string data includes the length of the NULL but excludes the length field. The only currently valid parameters are as - specified in + specified in . - 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,set-system-parameter with the same parameter - index. However, software may issue the + index. However, software may issue the ibm,set-system-parameter call again either earlier or later than this.
- +
HMC Parameter - The full HMC parameter data string is returned when the + The full HMC parameter data string is returned when the ibm,get-system-parameter RTAS call is issued. HMC parameter contents are: length - two byte binary length of data string associated with the @@ -19492,28 +19499,28 @@ The ibm,set-system-parameter is not required to support the HMC parameter since the HMC parameter data is set only by the HMC - through an out-of-band path. The + through an out-of-band path. The ibm,get-system-parameter RTAS call is provided for reading the parameter data. The RTAS call is available in both LPAR mode and non-LPAR mode. - + - R1-R1--1. - For the HMC Parameter: If the + For the HMC Parameter: If the ibm,set-system-parameter RTAS call is provided, the - use of the HMC parameters, 0-15, must always return not authorized + use of the HMC parameters, 0-15, must always return not authorized Status, -9002. - + - R1-R1--2. - For the HMC Parameter: The + For the HMC Parameter: The format of each HMC system parameter supported by this system must consist of a two byte binary length field describing the full length of the parameter data, followed @@ -19536,38 +19543,38 @@ HMC stops talking to the managed system. - + - R1-R1--3. - For the HMC Parameter: All + For the HMC Parameter: All HMC system parameter data must be printable ASCII characters, excluding the two byte binary length field. - + - R1-R1--4. - For the HMC Parameter: The + For the HMC Parameter: The lowest valued HMC system - parameter which returns a -3 + parameter which returns a -3 Status must have no higher valued HMC system parameter which is supported. That is, a scan of HMC system parameters - from 0 until the first -3 + from 0 until the first -3 Status must indicate all supported HMC system parameters. - + - R1-R1--5. - For the HMC Parameter: If + For the HMC Parameter: If there is no HMC control of this platform, the platform must return a null response, zero length data, to requests for all supported HMC system parameters. @@ -19575,7 +19582,7 @@ Implementation Note: Since the system is not necessarily to be HMC controlled, it is shipped with the HMC parameter set to the zero (0) length. If the system is HMC controlled, the HMC - passes the parameter values to the system at boot time so that the + passes the parameter values to the system at boot time so that the ibm,get-system-parameters RTAS call indicates HMC control. If there is deconfigured the HMC can write the zero (0) length data to the system. If that is not done, the system can write the @@ -19583,24 +19590,24 @@ initializes the data. - + - R1-R1--6. - For the HMC Parameter: The + For the HMC Parameter: The platform must truncate the HMC system parameter data at the buffer length if the buffer length is less than the data length plus 2. - +
- +
Capacity on Demand (CoD) Option - + Platforms may optionally provide mechanisms for securely licensing a subset of the platform’s physically installed resources for use. The CoD option includes system parameters relating to the CoD Capacity @@ -19621,25 +19628,25 @@ actually using the available resource the OS is using resources in excess of the permanently licensed entitlement until the failing CoD resource is returned to the platform. - + - R1-R1--1. - For the CoD option: The - platform must support the System Parameter option + For the CoD option: The + platform must support the System Parameter option (ibm,get-system-parameter) - along with Parameter tokens 18 - and 19 as described in + along with Parameter tokens 18 + and 19 as described in . - +
CoD Capacity Card Info - + Software Note: System parameters 18 and 19 present only permanently activated capacity. These parameters will be removed at @@ -19648,9 +19655,9 @@ These two read only system parameters (one for memory and another for processors) are ASCII hexadecimal strings representing the current licensed entitlement of CoD resources of their respective types. These - strings contains 9 packed fields as presented in + strings contains 9 packed fields as presented in . - + CoD Capacity Card Info String Packed Fields @@ -19755,43 +19762,43 @@
- + - R1-R1--1. - For the CoD option: The platform’s + For the CoD option: The platform’s ibm-get-system-parameter RTAS call, specifying the CoD Capacity Card Info, must, upon successful completion, return the - ASCII representation of the information defined in + ASCII representation of the information defined in for the managed CoD resource type specified by the system parameter token. - + - R1-R1--2. - For the CoD option: The platform’s + For the CoD option: The platform’s ibm,set-system-parameter RTAS call specifying the CoD - Capacity Card Info, must not return a - Status of 0 (success); the expected return is a + Capacity Card Info, must not return a + Status of 0 (success); the expected return is a Status of -9002 (Setting not allowed/authorized), - however, under special cases a + however, under special cases a Status of -1 (Hardware error), or one of the Busy or - Extended Delay return + Extended Delay return Status return values is allowed. - +
- +
Predictive Failure Sparing with Free Resources - + A platform may optionally provide an unused resource to a partition that is notified of a predictive failure. This allows the partition’s OS to transparently substitute the spare resource for @@ -19801,17 +19808,17 @@ DR RTAS calls to acquire the resource. In some cases resources are free because they have not been assigned to partitions. A platform may optionally provide an unused CoD resource to a - partition as a predictive failure spare. In such cases, the result of an + partition as a predictive failure spare. In such cases, the result of an get-sensor-state (entity-sense) for the DR slot returns the state of “exchange”. Between the time that the OS - takes ownership, via + takes ownership, via set-indicator (allocation-state, exchange), of the spare CoD resource available and the OS gives up the failing resource, the platform exceeds the licensed entitlement for that resource. - + - R1-R1--1. For the Predictive Failure Sparing option: @@ -19822,12 +19829,12 @@ - +
- +
Enhanced CoD Capacity Info - + These two read only system parameters (one for processor and one for memory) return ASCII hexadecimal strings representing the current licensed CoD resources. @@ -19836,22 +19843,22 @@ all optional sections. The caller should not expect the presence or order of all optional sections. Each optional section starts with the following 3 members: - - + + Offset to next section (zero for last section) - + Size in bytes of the section (including these three members) - + Name of the section - - + + The specific meaning of the members of each section is beyond the scope of this architecture; refer to the specific platform design documents. @@ -19862,19 +19869,19 @@ processor capacity is a fraction of a full processor, the data in the BaseProc section below is rounded up to the next larger whole number. - + - R1-R1--1. - For the CoD option: The platform's + For the CoD option: The platform's ibm,get-system-parameter RTAS call, specifying the Enhanced CoD Processor Capacity Info, must, upon successful completion, - return the ASCII representation of the information defined in + return the ASCII representation of the information defined in for managed CoD processor resources. - + Enhanced CoD Processor Capacity Info, Version 1 @@ -21172,18 +21179,18 @@
- + - R1-R1--2. - For the CoD option: The platform's + For the CoD option: The platform's ibm,get-system-parameter RTAS call, specifying the Enhanced CoD Memory Capacity Info, must, upon successful completion, - return the ASCII representation of the information defined in + return the ASCII representation of the information defined in for the managed CoD memory resources. - + Enhanced CoD Memory Capacity Info, Version 1 @@ -22451,38 +22458,38 @@
- + - R1-R1--3. - For the CoD option: The platform's + For the CoD option: The platform's ibm,set-system-parameter RTAS call specifying the - Enhanced CoD Capacity Info, must not return a - Status of 0 (Success); the expected return is a + Enhanced CoD Capacity Info, must not return a + Status of 0 (Success); the expected return is a Status of -9002 (setting not allowed/authorized), - however, under special cases a + however, under special cases a Status of -1 (Hardware Error) or one of the Busy or - Extended Delay return + Extended Delay return Status values is allowed. - +
- +
<emphasis>Restart Parameters</emphasis> - + This section and its subsections describe parameters that govern the actions that the platform firmware takes upon a restart (that is, reboot) after an unintended termination. - +
partition_auto_restart Parameter - + The partition_auto_restart parameter governs whether or not platform firmware attempts to restart a partition after an error which causes an abnormal partition termination. Neither a loss of external @@ -22495,10 +22502,10 @@ whether or not the entire platform restarts. If the platform does restart, however, partition_auto_restart determines whether or not an individual partition restarts. - + - R1-R1--1. For the LPAR option with the System Parameters @@ -22511,9 +22518,9 @@ 1 - Automatically restart the partition - + - R1-R1--2. For the SMP option (non-LPAR) with the System Parameters @@ -22527,22 +22534,22 @@ - +
- +
platform_auto_power_restart Parameter - + The platform_auto_power_restart parameter governs whether or not platform firmware attempts to restart after power is restored following a power outage. - + - R1-R1--1. - For the System Parameters option: If + For the System Parameters option: If the platform supports the platform_auto_power_restart system parameter, the platform must maintain across boot (unless explicitly altered by a user) one and @@ -22553,9 +22560,9 @@ power was lost. - + - R1-R1--2. For the LPAR option with the System Parameters @@ -22566,17 +22573,17 @@ - +
- +
- +
Remote Serial Port System Management Parameters - + - R1-R1--1. For the LPAR option with the System Parameters @@ -22585,25 +22592,25 @@ the platform must grant authority to set and read the single platform wide values of the respective system parameters to only the partition owning the resource required to implement the function, such as a serial - port, where the valid data for the parameters are specified in + port, where the valid data for the parameters are specified in . - + - R1-R1--2. - For the System Parameters option: The + For the System Parameters option: The platform must support the sp-rb4-pon system parameter if and only if the sp-remote-pon system parameter is supported and implemented by using “Ring Indicate” of a serial port. - + - R1-R1--3. For the LPAR option with the System Parameters @@ -22614,56 +22621,56 @@ time. - + - R1-R1--4. For the System Parameters option: To prevent return - data truncation of the returned sp-snoop-str system parameter from the + data truncation of the returned sp-snoop-str system parameter from the ibm,get-system-parameter RTAS call the caller must supply a buffer length sufficient to contain the two string length bytes plus the ASCII string and the terminating ASCII NULL. - + - R1-R1--5. - For the System Parameters option: The - caller of the + For the System Parameters option: The + caller of the ibm,get-system-parameter RTAS call must supply a buffer length sufficient to contain the two string length bytes plus the ASCII string and the terminating ASCII NULL to prevent return data truncation of the returned sp-snoop-str system parameter. - + - R1-R1--6. - For the System Parameters option: The + For the System Parameters option: The platform must supports both the sp-snoop-str and sp-serial-snoop system parameters if it supports either. - +
- +
Surveillance Parameters - + For the definition of the sp-sen, sp-sti, and sp-del parameters, - see + see . - + - R1-R1--1. For the LPAR option @@ -22671,14 +22678,14 @@ supports any of the following system parameters: sp-sen, sp-sti, or sp-del; the platform must grant authority to set and read the single platform wide one (1) byte values, where the decimal representation is - defined in + defined in , of the respective system parameters to only one partition at a time. - + - R1-R1--2. For the System Parameters option: If the platform @@ -22687,19 +22694,19 @@ - +
- +
Call Home Parameter - + This parameter is used to provide input concerning certain call home values used when a call home function is provided. The data for the parameter is an ASCII string which provides additional information - + - R1-R1--1. For the LPAR option with the System Parameters @@ -22710,38 +22717,38 @@ <String_name1>=<string><ASCII NULL><String_name2>=<string><ASCII NULL>....<String_nameN>=<string><ASCII - NULL><ASCII NULL> with string names defined as per + NULL><ASCII NULL> with string names defined as per . - + - R1-R1--2. - For the System Parameters option: The - caller of the + For the System Parameters option: The + caller of the ibm,get-system-parameter RTAS call must supply a buffer length sufficient to contain the maximum possible ASCII string - returned, including the two ASCII NULLs where + returned, including the two ASCII NULLs where indicates the maximum length of the data for each substring that comprises the sp-call-home data, to prevent return data truncation of the returned sp-call-home system parameter. - + - R1-R1--3. - For the System Parameters + For the System Parameters option: If the platform supports the sp-call-home parameter, the platform must provide the - sp-call-home parameter value defaults listed in - prior to any + sp-call-home parameter value defaults listed in + prior to any ibm,set-system-parameter RTAS call. - + sp-call-home Strings @@ -23289,82 +23296,82 @@ Notes: - - + + <N> is substituted with a modem number, i.e. 1 or 2. - + NULL as a default indicates that the string is given a name, but no value, e.g. sp-modemf-s= - + - + - +
Current Flash Image Parameter - + In systems with storage for more than one Flash image, the sp-current-flash-image parameter indicates which Flash image is currently being used by the service processor. This is typically the Flash image used at the last boot. - + - R1-R1--1. For the LPAR option with the System Parameters option: Platforms that supports the sp-current-flash-image system parameter, must authorize all partitions to get the single platform wide one (1) byte value of the - system parameter, whose decimal representation is defined in + system parameter, whose decimal representation is defined in . - + - R1-R1--2. For the System Parameters option: Platforms that - supports the sp-current-flash-image system parameter must support the + supports the sp-current-flash-image system parameter must support the ibm,manage-flash-image RTAS call. - +
- +
Platform Dump Max Size Parameter - + This parameter indicates the size (in bytes) needed for dumps - returned from the + returned from the ibm,platform-dump RTAS function. - + - R1-R1--1. - For the Platform Dump option: If the + For the Platform Dump option: If the ibm,platform-dump RTAS call is authorized for the partition, the platform must authorize the partition to get the platform-dump-max-size system parameter; where the value returned must indicate the sum (in bytes) of the maximum size of each unique platform - dump type that the + dump type that the ibm,platform-dump RTAS call could return. - + Programming Note: The intent of platform-dump-max-size is for the platform to specify, in advance, the @@ -23373,13 +23380,13 @@ type. In the case of any change in the value of this parameter, the platform may generate a Platform Event Log entry announcing the change in the maximum size, and specifying the new size in the IO Events Section. - This entry, when generated, is then returned by the + This entry, when generated, is then returned by the event-scan RTAS call.
- +
Storage Preservation Option System Parameters - + The epow3-quiesce-time system parameter contains the time granted to the current instance of a client program to perform quiesce activities in preparation for a memory preservation boot. This quiesce time is the @@ -23410,22 +23417,22 @@ not initiate the memory preservation boot timers. To use the memory preservation boot timers, the client program registers its LMBs for preservation and sets the - memory-preservation-boot-time via the + memory-preservation-boot-time via the ibm,set-system-parameter RTAS call. If an EPOW class 3 is sent to a client program and the client program has set its memory-preservation-boot-time parameter, then the platform starts the - timer for epow3-quiesce-time. The client program on reboot uses the + timer for epow3-quiesce-time. The client program on reboot uses the get-sensor RTAS call (to detect EPOW condition) and - the + the “ibm,preserved-storage” property in the device tree to drive memory preservation processing as necessary. The values of memory-preservation-boot-time and epow3-quiesce-time prior to being set for a client program are 0. These system parameters are persisted, as are all system parameters. - + - R1-R1--1. For the Storage Preservation option: The platform @@ -23433,16 +23440,16 @@ system parameters and must set their initial values to 0. - + - R1-R1--2. For the Storage Preservation option: If the memory-preservation-boot-time system parameter is non-zero for a client program and if the platform delivers an EPOW class 3 indication to the client program, the platform must do all of the following: - + Upon delivering the EPOW class 3 to the client program, if the epow3-quiesce-time system parameter is non-zero, then set a timer based @@ -23450,7 +23457,7 @@ force a reboot of the client program on timer expiration, if the client program does not request a reboot itself before the timer expires. - + Upon initiation of the memory preservation boot, set a timer based on the client program’s memory-preservation-boot-time system @@ -23458,31 +23465,31 @@ if the client program does not request a shutdown itself before the timer expires. - + - +
- +
SCSI Initiator Identifier System Parameters - + Certain physical SCSI IOAs maintain their previous settings for SCSI initiator identifier, while others require that the platform set this value during I/O adapter initialization. Since the initialization of I/O adapters in the boot path is done by firmware, a method is required for the OS to inform the platform firmware of such settings. Given that an OS owns a slot, and that slot contains a supported SCSI I/O adapter, - the OS may use the + the OS may use the ibm,set-system-parameter RTAS call specifying SCSI Initiator Identifier system parameters to instruct the firmware how to initialize the I/O adapter to ensure that it does not conflict with other - SCSI initiators on the same bus. The + SCSI initiators on the same bus. The ibm,get-system-parameter RTAS call is used to verify the SCSI Initiator Identifier system parameters value for any OS owned slot. - When + When ibm,set-system-parameter is called specifying SCSI Initiator Identifier system parameters, the buffer contains the standard two byte length field plus two NULL terminated strings. The first string @@ -23490,7 +23497,7 @@ the second string contains one of the decimal values 0-15 representing the value of the SCSI Initiator Identifier that the platform's firmware is to use to initialize the SCSI controller for that bus. - When + When ibm,get-system-parameter is called specifying SCSI Initiator Identifier system parameters, the buffer contains the standard two byte length field plus a NULL terminated string that contains the @@ -23516,183 +23523,183 @@ firmware clears the SCSI Initiator Identifier system parameters for the location code and performs the platform default IOA initialization. - + - R1-R1--1. For the SCSI Initiator Identifier System Parameters option: When ibm,set-system-parameter is called specifying SCSI - Initiator Identifier system parameters, RTAS must return + Initiator Identifier system parameters, RTAS must return Status of -3 (Parameter error) on any of the following conditions: - - + + The binary value of the first two bytes in the buffer, plus 2, is greater than the buffer length parameter. - + The buffer length parameter is greater than 1026. - + The N bytes of buffer contents (N being the binary value of the first two buffer bytes) does not contain two NULL terminated strings. - + The contents of the first NULL terminated buffer string does not match the format of a valid platform location code. - + The contents of the second NULL terminated buffer string does not contain a decimal value in the range of 0 to 15. - + - + - R1-R1--2. For the SCSI Initiator Identifier System Parameters option: When ibm,set-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the first NULL terminated buffer string must contain a valid formatted platform location code for a currently installed slot owned by the calling OS, or the platform must - return “Not authorized” + return “Not authorized” Status. - + - R1-R1--3. For the SCSI Initiator Identifier System Parameters option: When ibm,set-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the first NULL terminated buffer string must contain a valid formatted platform location code for a SCSI bus connector of a supported SCSI I/O adapter currently installed in a slot owned by the calling OS, or the platform must return - “Parameter Error” + “Parameter Error” Status. - + - R1-R1--4. For the SCSI Initiator Identifier System Parameters - option: When + option: When ibm,set-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the firmware must record the value supplied in the second NULL terminated buffer string for use in initializing the SCSI initiator identifier of the SCSI I/O adapter contained in the slot specified by the first NULL terminated buffer - string and return a + string and return a Status of 0 (success) (except in the case of hardware errors or busy conditions). - + - R1-R1--5. For the SCSI Initiator Identifier System Parameters option: When ibm,get-system-parameter is called specifying SCSI - Initiator Identifier system parameters, RTAS must return a + Initiator Identifier system parameters, RTAS must return a Status of -3 (Parameter error) on any of the following conditions: - - + + The binary value of the first two bytes in the buffer, plus 2, is greater than the buffer length parameter. - + The buffer length parameter is greater than 1026. - + The N bytes of buffer contents (N being the binary value of the first two buffer bytes) does not contain one NULL terminated string. - + The contents of the NULL terminated buffer string does not match the format of a valid platform location code. - + - + - R1-R1--6. For the SCSI Initiator Identifier System Parameters option: When ibm,get-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the NULL terminated buffer string must contain a valid formatted platform location code for a currently installed slot owned by the calling OS, or the platform must - return “Not authorized” + return “Not authorized” Status. - + - R1-R1--7. For the SCSI Initiator Identifier System Parameters option: When ibm,get-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the NULL terminated buffer string must contain a valid formatted platform location code for a SCSI bus connector of a supported SCSI I/O adapter currently installed in a - slot owned by the calling OS, or the platform must return a + slot owned by the calling OS, or the platform must return a Status of -3 (parameter error). - + - R1-R1--8. For the SCSI Initiator Identifier System Parameters - option: When + option: When ibm,get-system-parameter is called specifying SCSI Initiator Identifier system parameters, and the request successfully - passes the Requirements of + passes the Requirements of , the firmware must: - - + + Increase the value contained in the first two bytes of the buffer to cover both the length of the location code NULL terminated @@ -23701,7 +23708,7 @@ I/O adapter contained in the slot specified by the first NULL terminated buffer string. - + If there is room in the buffer, append the NULL terminated string representing the decimal value that the platform uses to @@ -23709,17 +23716,17 @@ contained in the slot specified by the first NULL terminated buffer string. - + - Return a Status of 0 (success) (except in the + Return a Status of 0 (success) (except in the case of hardware errors or busy conditions). - + - + - R1-R1--9. For the SCSI Initiator Identifier System Parameters @@ -23734,22 +23741,22 @@ - +
- +
CoD Options - + The CoD Options system parameter allows specification of various CoD options. - + - R1-R1--1. - ibm,get-system-parameter is called - specifying the CoD Options system parameter, the first + ibm,get-system-parameter is called + specifying the CoD Options system parameter, the first two bytes of the value returned must contain the full length of the parameter data, including the length of the NULL. The two byte binary length field is followed by a variable of @@ -23759,15 +23766,15 @@ character string. - + - R1-R1--2. The corresponding keyword and values - for the CoD Options parameter are defined in + for the CoD Options parameter are defined in . - +
CoD Options System Parameter Keyword and Values @@ -23817,38 +23824,38 @@ - + - +
Platform Error Classification - + The Platform Error Classification system parameter specifies whether the OS should process platform reported errors as informational errors as opposed to service actionable events. - + - R1-R1--1. - When + When ibm,get-system-parameter is called specifying the Platform Error Classification system parameter, the platform must return - a value of - “1” if all errors returned in - event-scan, - check-exception, - rtas-last-error and + a value of + “1” if all errors returned in + event-scan, + check-exception, + rtas-last-error and ibm,slot-error-detail calls should be treated as informational errors in the sense that they not be reported by service applications as service actionable events and otherwise must return a - value of + value of “0”. - + Programming Note: Service applications within an operating system may obtain information about platform errors and take @@ -23870,16 +23877,16 @@ the log based on the parameter. Rather it is left to service applications to query the system parameter and take actions based on it.
- +
Firmware Boot Options - + The Firmware Boot Options system parameter allows specification of various firmware boot settings. - + - R1-R1--1. When ibm,get-system-parameter is called specifying the @@ -23892,12 +23899,12 @@ must be an ASCII printable character string. - + - R1-R1--2. - When ibm,set-system-parameter is + When ibm,set-system-parameter is called specifying the Firmware Boot Options system parameter, the first two bytes of the buffer must be binary and must contain the full length of the parameter data, @@ -23910,15 +23917,15 @@ must return with a status of -9002. - + - R1-R1--3. Keyword and values for the Firmware - Boot Options parameter must be as defined in + Boot Options parameter must be as defined in . - +
Firmware Boot Options System Parameter Keywords and Values @@ -23968,83 +23975,83 @@ - + - +
Platform Processor Diagnostics Options - + The platform-processor-diagnostics-run-mode system parameter allows the operating system to query or control how platform run-time processor diagnostics are executed by the platform. Provision is made by this parameter for the platform to execute run-time diagnostic tests to verify various processor functions. These diagnostics tests typically would be performed by the hypervisor against each processor in the system. - + - R1-R1--1. - When + When ibm,get-system-parameter is called with the platform-processor-diagnostics-run-mode token, the platform must return a one-byte parameter indicating the current run-mode of platform processor diagnostics as one of the following: - - + + 0 = disabled: indicates that the platform will not run processor run-time diagnostics. - + 1 = staggered: indicates that the platform is set to run processor diagnostics on each processor on a periodic basis, but not attempt to schedule the tests for all processors at the same time. The frequency at which the tests will run are defined by the platform. - + 2 = immediate: indicates that the platform is currently in the processor of running diagnostics against the processors in a system on a non-staggered basis, either as a result of an “immediate” or “periodic” setting. - + 3 = periodic: indicates that the platform is scheduled to run diagnostics against all the processors in the system at a specific time scheduled by the platform. - + - + - R1-R1--2. - When + When ibm,set-system-parameter is called specifying the platform-processor-diagnostics-run-mode token, the one-byte parameter passed must indicate the run-mode of platform periodic diagnostics desired as one of the following: - - + + 0 = disabled: indicates that the platform should not run any processor run-time diagnostics. Any currently running diagnostics will be terminated. - + 1 = staggered: indicates that the platform should run diagnostics periodically against each processor in the system, but not attempt to schedule the tests for all processors at the same time. The frequency at which the tests will run are defined by the platform. - + 2 = immediate: indicates that the platform should immediately begin the process of running processor diagnostics on all of the @@ -24055,11 +24062,11 @@ “periodic” once the immediately run diagnostics are complete. - + - + Implementation Notes: To prevent conflicts in the setting of the run-mode, the platform should only support this parameter @@ -24067,22 +24074,22 @@ platform. The last value set will take precedent over any previous settings.
- +
Processor Module Information - + The Processor Module Information system parameter allows transferring of certain processor module information from the platform to the OS. The information in the parameter is global for the platform and encompasses all resources on the platform, not just those available to - the partition, and the - ibm,get-system-parameter will never return a + the partition, and the + ibm,get-system-parameter will never return a Status of -9002 (Not Authorized). This parameter is read-only. - + - R1-R1--1. For the LPAR option with the System Parameters @@ -24099,34 +24106,34 @@ type. - + - R1-R1--2. For the LPAR option with the System Parameters option: For the Processor Module Information system parameter, - the + the ibm,get-system-parameter RTAS call must never return - a - Status of -9002 (Not Authorized), and the + a + Status of -9002 (Not Authorized), and the ibm,set-system-parameter RTAS call must always return a Status of -9002 (Setting not allowed/authorized). - +
- +
Cede Latency Settings Information - + The Cede Latency Settings Information system parameter informs the OS of the maximum latency to wake up from the various platform supported processor sleep states that it might employ for idle processors. The information in the parameter is global for the platform and encompasses - all processors on the platform, and the - ibm,get-system-parameter will never return a + all processors on the platform, and the + ibm,get-system-parameter will never return a Status of -9002 (Not Authorized). This parameter is read-only. As the architecture evolves, the number of fields per record are likely to increase, calling software should be written to handle @@ -24138,31 +24145,31 @@ settings (and thus the number of reported records) and the number of fields reported per record might change from call to call; calling software should be written to handle this variability - + - R1-R1--1. For the PEM option with the System Parameters option: If the platform supports the cede latency settings information system parameter it must provide the following information in the NULL terminated parameter string: - - + + The first byte is the binary length “N” of each cede latency setting record minus one (zero indicates a length of 1 byte) - + For each supported cede latency setting a cede latency setting - record consisting of: The first “N” bytes of + record consisting of: The first “N” bytes of . - - + +
Byte definitions within a cede latency setting record @@ -24245,99 +24252,99 @@
- + - R1-R1--2. For the PEM option with the System Parameters - option: For the cede latency specifier system parameter, the + option: For the cede latency specifier system parameter, the ibm,get-system-parameter RTAS call must never return - a - Status of -9002 (Not Authorized), and the + a + Status of -9002 (Not Authorized), and the ibm,set-system-parameter RTAS call must always return - a + a Status of -9002 (Setting not allowed/authorized). - +
- +
Target Active Memory Compression Factor - + The target active memory compression factor system parameter informs the OS of the target memory capacity increase the customer expects to achieve due to active memory compression. The factor is expressed in whole percentage with the minimum value of 100 and the maximum value of 1000. - The + The ibm,get-system-parameter for parameter token 46 will - never return a + never return a Status of -9002 (Not Authorized). This parameter is read-only. - + - R1-R1--1. For the Active Memory Compression option with the System Parameters option: For the Target Active Memory Compression - Factor system parameter, the + Factor system parameter, the ibm,get-system-parameter RTAS call must never return a Status of -9002 (Not Authorized). - + - R1-R1--2. For the Active Memory Compression option with the System Parameters option: If the Active Memory Compression option is - enabled for the partition, the platform must provide in response to the + enabled for the partition, the platform must provide in response to the ibm,get-system-parameter for parameter token 46 the two byte target active memory compression factor in binary format in the range (0x0064 -- 0x03E8) (equivalent to 100 -- 1000 decimal). - + - R1-R1--3. For the Active Memory Compression option with the System Parameters option: If the Active Memory Compression option is disabled for the system/partition, the platform must provide in response - to the + to the ibm,get-system-parameter for parameter token 46 the two byte value 0x0000. - + - R1-R1--4. For the Active Memory Compression option with the System Parameters option: For the target active memory compression - factor system parameter, the + factor system parameter, the ibm,set-system-parameter RTAS call must always return a Status of -9002 (Setting not allowed/authorized). - +
- +
Performance Boost Modes Vector - + A variety of platform dependent configuration modes might result in - a boost in platform computational capacity. The + a boost in platform computational capacity. The ibm,get-system-parameter through the performance boost modes vector system parameter communicates to the client program which of these modes are available on the specific platform, which of @@ -24345,21 +24352,21 @@ active. The performance boost mode vectors are 32 bytes (256 bits) long. Each bit position within the performance boost mode vector corresponds to - a specific function as specified in + a specific function as specified in . The first defined boost mode is assigned to the highest order bit position. As new boost modes are defined, they are assigned to sequential lower order vector bit positions. - Given that the second version of the vector from the + Given that the second version of the vector from the ibm,get-system-parameter RTAS call (specifying which modes may be enabled/disabled by the client program) is non-zero, the - platform supports calling the + platform supports calling the ibm,set-system-parameter RTAS call specifying the - performance boost modes vector token. The + performance boost modes vector token. The ibm,set-system-parameter RTAS call specifying the performance boost modes vector token takes a single vector as input. - + Performance Boost Modes Vector Bits Definitions @@ -24401,188 +24408,188 @@
- + - R1-R1--1. For the Performance Boost Modes option: The platform must implement the System Parameters option. - + - R1-R1--2. For the Performance Boost Modes option: The 96 byte - report returned by + report returned by ibm,get-system-parameter for parameter token 47 must - consist of three 32 byte bit vectors as defined by + consist of three 32 byte bit vectors as defined by . - + - R1-R1--3. For the Performance Boost Modes option: The first 32 - byte bit vector returned by + byte bit vector returned by ibm,get-system-parameter for parameter token 47 must - contain 1s in the bit positions define by + contain 1s in the bit positions define by for the performance boost modes that are both supported by the platform and authorized for the caller (by means outside of the scope of LoPAR). - + - R1-R1--4. For the Performance Boost Modes option: The second 32 - byte bit vector returned by + byte bit vector returned by ibm,get-system-parameter for parameter token 47 must - contain 1s in the bit positions define by + contain 1s in the bit positions define by for the performance boost modes that are both represented in the first vector and may be enabled/disabled - by the caller through the + by the caller through the ibm,set-system-parameter using parameter token 47. - + - R1-R1--5. For the Performance Boost Modes option: The third 32 - byte bit vector returned by + byte bit vector returned by ibm,get-system-parameter for parameter token 47 must - contain 1s in the bit positions define by + contain 1s in the bit positions define by for the performance boost modes that are both represented in the first vector and are enabled either by - default or by the caller through the + default or by the caller through the ibm,set-system-parameter using parameter token 47. - + - R1-R1--6. - For the Performance Boost Modes option: If the + For the Performance Boost Modes option: If the ibm,get-system-parameter for parameter token 47 communicated that the client program has the ability to enable/disable one or more of the boost modes, then the platform must support the performance boost modes vector token for ibm,set-system-parameter. - + - R1-R1--7. For the Performance Boost Modes option: If no boost modes can be enabled/disabled then a call to ibm,set-system-parameter specifying the boost modes vector token must return either: - - + + “System parameter not supported” as indeed the implementation need not code support for the token if no mode setting is supported. - + “Setting not allowed/authorized” if the implementation supports setting boost modes but the caller is not authorized to do so. - + - + - R1-R1--8. For the Performance Boost Modes option: If any input - vector to the + vector to the ibm,set-system-parameter RTAS for parameter token 47 is a one and does not correspond to a bit that is a one in the second - version of the vector returned by the + version of the vector returned by the ibm,get-system-parameter RTAS for parameter token 47 the ibm,set-system-parameter RTAS must return parameter error. - + - R1-R1--9. For the Performance Boost Modes option: If the corresponding bit that was a one in the second version of the vector - returned by the + returned by the ibm,get-system-parameter RTAS for parameter token 47 - is a one in the input vector to the + is a one in the input vector to the ibm,set-system-parameter RTAS for parameter token 47 then upon successful return that corresponding boost mode must be enabled. - + - R1-R1--10. For the Performance Boost Modes option: If the corresponding bit that was a one in the second version of the vector - returned by the + returned by the ibm,get-system-parameter RTAS for parameter token 47 - is a zero in the input vector to the + is a zero in the input vector to the ibm,set-system-parameter RTAS for parameter token 47 then upon successful return that corresponding boost mode must be disabled. - + - R1-R1--11. For the Performance Boost Modes option: To properly awake from partition suspension and handle dynamic reconfiguration, the client program must be prepared to handle changes in the bit settings - within the bit vectors reported by the + within the bit vectors reported by the ibm,get-system-parameter RTAS for parameter token 47. - + - R1-R1--12. For the Performance Boost Modes option: Since it is - expected that bit positions define by + expected that bit positions define by will expand over time, to avoid firmware level compatibility issues, the client program must ignore bit - settings within the bit vectors reported by the + settings within the bit vectors reported by the ibm,get-system-parameter RTAS for parameter token 47 beyond those defined when the client pr gram was designed. - +
- +
TLB Block Invalidate Characteristics - + The Block Invalidate option allows for the removal of multiple page table entries with a single platform wide TLB invalidate sequence, providing significantly improved performance when removing a virtual memory object. The size of the block (the number of consecutive virtual memory pages) that is processed by a single TLB invalidate sequence is @@ -24594,7 +24601,7 @@ Characteristics Specifier Format‚” on page 253. If the implementation invalidates different sized blocks for different page size encodings, there will be multiple “TLB Block Invalidate Characteristics Specifiers” within the returned string. - + TLB Block Invalidate Characteristics Specifier Format @@ -24663,75 +24670,75 @@ 2 - 7 - Encoded segment base page size and actual page size per + Encoded segment base page size and actual page size per Book IVa
- + - R1-R1--1. - For the Block Invalidate option with the + For the Block Invalidate option with the System Parameters option: For the Block Invalidate system - parameter, the ibm,get-system-parameter RTAS call must + parameter, the ibm,get-system-parameter RTAS call must never return a Status of -9002 (Not Authorized). - + - R1-R1--2. - For the Block Invalidate option with the - System Parameters option: If the Block Invalidate option - is enabled for the partition, the platform must provide in response + For the Block Invalidate option with the + System Parameters option: If the Block Invalidate option + is enabled for the partition, the platform must provide in response to the ibm,get-system-parameter for - parameter token 50 the one or more TLB Block Invalidate + parameter token 50 the one or more TLB Block Invalidate Specifiers for the calling partition as described in . - + - R1-R1--3. - For the Block Invalidate option with the + For the Block Invalidate option with the System Parameters option: If the Block Invalidate - option is disabled for the system/partition, the platform must - provide in response to the ibm,get-system-parameter + option is disabled for the system/partition, the platform must + provide in response to the ibm,get-system-parameter for parameter token 50 the two byte value 0x0000. - + - R1-R1--4. - For the Block Invalidate option with the + For the Block Invalidate option with the System Parameters option: For the Block Invalidate - system parameter, the ibm,get-system-parameterRTAS call must + system parameter, the ibm,get-system-parameterRTAS call must always return a Status of -9002 (Setting not allowed/authorized).
- +
Energy Management Tuning Parameters (EMTP) - - The energy management tuning parameters are reported. Each parameter occupies - its own 8 byte self-defining entry. As many energy management tuning parameter entries - as are supported by the system are reported, subject to the limitation of the buffer - length. Each reported parameter entry is formatted per + + The energy management tuning parameters are reported. Each parameter occupies + its own 8 byte self-defining entry. As many energy management tuning parameter entries + as are supported by the system are reported, subject to the limitation of the buffer + length. Each reported parameter entry is formatted per . - + Format of the Energy Management Tuning Parameter Entry @@ -24758,11 +24765,11 @@ - Parameter IdentifierSee + Parameter IdentifierSee for definition values. - Parameter UnitsSee + Parameter UnitsSee for definition values. @@ -24853,8 +24860,8 @@   - All other Parameter ID Values are reserved, should calling software - encounter a parameter id value which was reserved at the time it was + All other Parameter ID Values are reserved, should calling software + encounter a parameter id value which was reserved at the time it was written, it shall ignore the specific entry, and only that entry. @@ -24897,8 +24904,8 @@   - All other Parameter Unit Values are reserved, should calling software - encounter a parameter unit value which was reserved at the time it was + All other Parameter Unit Values are reserved, should calling software + encounter a parameter unit value which was reserved at the time it was written, it shall ignore the specific entry, and only that entry. @@ -24908,52 +24915,52 @@ - R1-R1--1. For the EMTP option with the System Parameters option: - For the EMTP system parameter, the ibm,get-system-parameter RTAS call + For the EMTP system parameter, the ibm,get-system-parameter RTAS call must never return a Status of -9002 (Not Authorized). - + - R1-R1--2. For the EMTP option with the System Parameters option: - If the EMTP option is enabled for the partition, the platform must provide in response to the - ibm,get-system-parameter for parameter token 52 the Energy Management + If the EMTP option is enabled for the partition, the platform must provide in response to the + ibm,get-system-parameter for parameter token 52 the Energy Management Tuning Parameters for the calling system as described in this section. - + - R1-R1--3. For the EMTP option with the System Parameters option: - If the EMTP option is disabled for the system/partition, the platform must provide in - response to the ibm,get-system-parameter for parameter token 52 the + If the EMTP option is disabled for the system/partition, the platform must provide in + response to the ibm,get-system-parameter for parameter token 52 the two byte value 0x0000. - + - R1-R1--4. For the EMTP option with the System Parameters option: - For the EMTP system parameter, the ibm,set-system-parameter RTAS call + For the EMTP system parameter, the ibm,set-system-parameter RTAS call must always return a Status of -9002 (Setting not allowed/authorized). - + - + diff --git a/RTAS/sec_rtas_get_indices.xml b/RTAS/sec_rtas_get_indices.xml index 1a52c84..e3d0546 100644 --- a/RTAS/sec_rtas_get_indices.xml +++ b/RTAS/sec_rtas_get_indices.xml @@ -5278,6 +5278,13 @@ The OS completes/invalidates current dump status. + + + The OS must use H_CLEAR_HPT to clear the page table if running + in XIVE Exploitation Mode, H_REMOVE is not a sufficient mechanism + to clear the HPT. Failure to use H_CLEAR_HPT may result in H_READ + returning invalid entries as valid. + diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml index ed535ac..fc89056 100644 --- a/Virtualization/ch_lpar_option.xml +++ b/Virtualization/ch_lpar_option.xml @@ -913,6 +913,116 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Accepts pending interrupt + + + + / + + + + Get the ESB addresses for a LISN + + + + + + / + + + + Assign a target and priority to a LISN + + + + + + / + + + + Get the target and priority assigned to a LISN + + + + + + / + + + + Get the notification management page for a LISN + + + + + + / + + + + Set/Reset an EQ for a target and priority + + + + + + / + + + + Get the EQ set for a target and priority + + + + + + / + + + + Set the OS reporting cache line pair for a target + + + + + + / + + + + Get the OS reporting cache line pair for a target + + + + + + / + + + + Load or store operation on the ESB page for a LISN + + + + + + / + + + + Issue the requested sync + + + + + + / + + + + Reset interrupt state to the initial state + + @@ -4319,6 +4429,215 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo hcall-imtt + + + + / + + + + 0x3A8 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3AC + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3B0 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3B4 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3B8 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3BC + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3C0 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3C4 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3C8 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3CC + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + + + + + / + + + + 0x3D0 + + + Normal + + + If the OS enabled XIVE exploitation + + + hcall-int-exploitation + + hcalls to support an Ultravisor @@ -9840,9 +10159,320 @@ hcall ( const uint64 H_CLEAR_HPT);]]>
Interrupt Support hcall()s - Injudicious values written to the interrupt source controller may - affect innocent partitions. The following hcall()s monitor the - architected functions. + + + below describes legacy vs exploitation differences related to the client + architecture, device tree and hcalls. The symbol @ESB refers to a logical + real address returned from the hcall() + . The symbol + @TIMA refers to the logical real address in the + “reg” + property of the + External Interrupt Virtualization Node. + +
+ XIVE Legacy vs. Exploitation Mode Hypervisor Call Function Table + + + + + + + + Legacy + + + + + Exploitation Mode + + + + + + + + Client Architecture Support + Option Vector 5 Byte 23 bits 0-1 undefined or 0b00 + + /chosen + “ibm,architecture-vec” Byte 23 bits 0-1 undefined or 0b00 + See ibm,architecture vector 5, byte 23 in + + for more details. + + + + + + Client Architecture Support + Option Vector 5 Byte 23 bits 0-1 undefined or 0b00 + + /chosen + “ibm,architecture-vec” Byte 23 bits 0-1 value 0b01 + + + + + + “ibm,get-xive” + + + hcall() + + + + + “ibm,set-xive” + + + hcall() + hcall() + + + + + “ibm,int-off” + + + CI load double to @ESB + 0xD00 + See XIVE specification for details on the CI operations. + + + + + + “ibm,int-on” + + + CI load double to @ESB + 0xC00 + + + + + “set-indicator” with indicator 9005 + + + Same + + + + + “get-sensor-state” with indicator 9005 + + + Same + + + + + H_EOI + + + CI load double to @ESB + 0xC00 if store EOI is not + enabled + CI store double to @ESB + 0x400 if store EOI is + enabled + CI store byte to @TIMA + 0x11 of pre-interrupt + CPPR + + + + + + H_CPPR + + + CI store byte to @TIMA + 0x11 of new CPPR + + + + + H_IPI + + + CI store byte to @ESB + 0x00 + + + + + H_IPOLL + + + CI load byte from @TIMA + 0x10 + + + + + H_XIRR + + + CI load half word from @TIMA + 0x810 + + + + + H_XIRR-X + + + Deprecated + + + + + H_VIO_SIGNAL + + + Same + The following are clarified in the hcall definition: + + + A race between a VIO virtual adapter generating a new + interrupt and a H_VIO_SIGNAL() or H_VIOCTL() hcall + could have multiple outcomes. H_VIO_SIGNAL()/H_VIOCTL() + wins and the interrupt does not occur, or the new interrupt + wins and one device interrupt occurs after H_VIO_SIGNAL()/H_VIOCTL() + call returns. + + + Interrupting events that occur while H_VIO_SIGNAL()/H_VIOCTL() + has disabled interrupts will never generate an interrupt. + + + + + + + + H_VIOCTL with sub functions: + DISABLE_ALL_VIO_INTERRUPTS + DISABLE_VIO_INTERRUPT + ENABLE_VIO_INTERRUPT + + + Same + + + + +
+ + + + Hypervisor Call Functions Unique to XIVE Exploitation + + + + + + + + Function Description + + + + + HCALL + + + + + + + + Get the ESB addresses for a LISN + + + + + + + + Assign a target and priority to a LISN + + + + + + + + Get the target and priority assigned to a LISN + + + + + + + + Get the notification management page for a LISN + + + + + + + + Set/Reset an EQ for a target and priority + + + + + + + + Get the EQ set for a target and priority + + + + + + + + Set the OS reporting cache line pair for a target + + + + + + + + Get the OS reporting cache line pair for a target + + + + + + + + Load or store operation on the ESB page for a LISN + + + + + + + + Issue the requested sync + + + + + + + + Reset interrupt state to the initial state + + + + + + + +
+ + Injudicious values written to the interrupt source controller may + affect innocent partitions. The following hcall()s monitor the + architected functions.
H_EOI @@ -10143,6 +10773,1411 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */
+ +
+ H_INT_GET_SOURCE_INFO + + The H_INT_GET_SOURCE_INFO hcall() is used to obtain the logical real + address of the MMIO page through which the Event State Buffer entry + associated with the value of the “lisn” parameter is managed. + The initial state of the ESB PQ bits will be the architected off value + of 0b01. The “lisn” parameter can come from several different properties + or hcalls. For example, the “lisn” parameter value for I/O adapters is + passed to a partition through the + “interrupts” and + “interrupt-map” properties + in the device tree node describing the I/O adapter. Alternatively, for + inter processor interrupts, the “lisn” parameter is a value the OS chooses + from a range of LISNs from the + “ibm,xive-lisn-ranges” property. + While for platform accelerators, the “lisn” parameter is a value returned + by the allocating hcall(), H_ALLOCATE_VAS_WINDOW. Depending upon the specific + Logical Interrupt Source, there might be either one or two page addresses + assigned to the Logical Interrupt Source as indicated by the returned values + of this hcall(). The hcall() returns four values in addition to the return code. + The first value is the logical real address of the full function page address, + which allows both trigger and reset functions. The second value is either the + logical real address of the trigger only page, or the reserved value -1 (all ones). + The value of -1 indicates that the Event Source Buffer does not have a trigger only page. + + See the XIVE specification for more details on the full function + page versus the trigger only page. + + + + Syntax: + + + + + Parameters: + + + + flags: bits 0-63 reserved + + + + “lisn” is per + “interrupts”, + “interrupt-map”, or + “ibm,xive-lisn-ranges” properties, + or as returned by the + ibm,query-interrupt-source-number + RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall + + + + + + Return Values: + + + + R4: “flags”: + + + Bits 0-59: Reserved + + + + Bit 60: ESB hcall: ESB hcall==1, hcall() H_INT_ESB must be + used for Event State Buffer management + + + + Bit 61: LSI: LSI==1, the interrupt associated with the + “lisn” is a LSI (Level Sensitive Interrupt), LSI==0, the + interrupt associated with the “lisn” is a MSI (Message Signaled Interrupt) + + + + Bit 62: Trigger: Trigger==1, the full function page supports trigger + + + + Bit 63: Store EOI Supported + + + + + + + R5: Logical Real address of full function Event State Buffer + management page, -1 if ESB hcall flag is set to 1. + + + + R6: Logical Real Address of trigger only Event State Buffer + management page or -1 if ESB hcall flag is set to 1. + + + + R7: Power of 2 page size for the ESB management pages returned + in R5 and R6. For example, a 4K page size is represented by the value + of 12 (4K = 212). There is a minimum page size of 4K. + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “lisn” parameter per the list of interrupt sources + allocated to the calling partition else return H_P2. + + + + Load R4 with the return flags, setting the reserved bits to 0. + + + + Load R5 with the logical real address of the full function Event + State Buffer management page. + + + + If the associated Event State Buffer has two management pages + defined load the logical real address of the trigger only page into + R6 else load R6 with -1. + + + + Load R7 with the power of 2 page size of the ESB management pages. + + + + Return H_Success. + + + +
+ +
+ H_INT_SET_SOURCE_CONFIG + + The H_INT_SET_SOURCE_CONFIG hcall() is used to assign a Logical Interrupt + Source to a target. The Logical In- terrupt Source is designated with the + “lisn” parameter and the target is designated with the “target” and + “priority” parameters. Upon return from the hcall(), no additional interrupts + will be directed to the old EQ. The old EQ should be investigated for + nterrupts that occurred prior to or during the hcall(). + + + Syntax: + + + + + Parameters: + + + + “flags” + + + Bits 0-61: Reserved + + + + Bit 62: setEisn: setEisn==1, set the “eisn” in the EA + + + + Bit63: M: m==1 masks the interrupt source in the hardware + interrupt control structure. + As defined in Section 3.7 "Processing an EAS" in + the XIVE Specification. + An interrupt masked by this mechanism will be dropped, but + it's source state bits will still be set. There is no race-free + way of unmasking and restoring the source. Thus this should only + be used in interrupts that are also masked at the source, and + only in cases where the interrupt is not meant to be used for + a large amount of time be- cause no valid target exists for it + for example + + + + + + + + “lisn” is per + “interrupts”, + “interrupt-map”, or + “ibm,xive-lisn-ranges” properties, + or as returned by the + ibm,query-interrupt-source-number RTAS call, or + as returned by the H_ALLOCATE_VAS_WINDOW hcall + + + + “target” is per + “ibm,ppc-interrupt-server#s” or + “ibm,ppc-interrupt-gserver#s” + + + + “priority” is a valid priority not in + “ibm,plat-res-int-priorities” + + + + “eisn” is the guest EISN associated with the “lisn” + + + + + + Return Values: + + None + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “lisn” parameter per the list of interrupt sources + allocated to the calling partition else return H_P2. + + + + If “priority” is not 0xFF + + + Validate the “target” parameter per the list of threads + allocated to the calling partition else return H_P3. + + + + If the partition thread count is greater than the hardware + thread count, validate the “target” has a corresponding hardware + thread else return H_Not_Available. + + + + Validate the “priority” parameter is a valid priority + and not in listed in the + “ibm,plat-res-int-priorities” + property else return H_P4. + + + + Fill the Event Assignment Structure associated with “lisn” with: + + + Block and Event Notification Descriptor Table Index + associated with “target”/”priority” pair. + + + + Set the “M” bit to the value of the flags “M” bit. + + + + If setEisn==1, store “eisn”. + + + + Issue syncs required to ensure all in-flight + interrupts are complete. + + + + + + + + + + Else + + + Reset the Event Assignment Structure associated with “lisn” by: + + + Issue syncs required to ensure all in-flight interrupts + are complete + + + + Invalidating the Block and End Notification Descriptor + Table Index + + + + Resetting the eisn + + + + + + + + + + Return H_Success. + + + +
+ +
+ H_INT_GET_SOURCE_CONFIG + + The H_INT_GET_SOURCE_CONFIG hcall() is used to determine to which + target/priority pair is assigned to the specified Logical Interrupt Source. + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + “lisn” is per + “interrupts”, + “interrupt-map”, or + “ibm,xive-lisn-ranges” properties, + or as returned by the + ibm,query-interrupt-source-number RTAS call, or as returned by the + H_ALLOCATE_VAS_WINDOW hcall + + + + + + Return Values: + + + + R4: Target to which the specified Logical Interrupt Source is + assigned, else this is undefined. + + + + R5: Priority to which the specified Logical Interrupt Source is + assigned, else this is set to 0xFF (disabled). + + + + R6: EISN for the specified Logical Interrupt Source (this will + be equivalent to the LISN if not changed by H_INT_SET_SOURCE_CONFIG). + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “lisn” parameter per the list of interrupt sources + allocated to the calling partition else return H_P2. + + + + Load R4 with the target associated with the “lisn” parameter. + + + + Load R5 with the priority associated with the “lisn” parameter. + + + + Load R6 with the EISN associated with the “lisn” parameter. + + + + Return H_Success. + + + +
+ +
+ H_INT_GET_QUEUE_INFO + + The H_INT_GET_QUEUE_INFO hcall() is used to get the logical real + address of the notification management page7 associated with the + specified target and priority. + + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + “target” is per + “ibm,ppc-interrupt-server#s” or + “ibm,ppc-interrupt-gserver#s” + + + + “priority” is valid priority not in the + “ibm,plat-res-int-priorities” + + + + + + Return Values: + + + + R4: Logical real address of notification page + + + + R5: Power of 2 page size of the notification page + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “target” parameter per the list of threads allocated + to the calling partition else return H_P2. + + + + If the partition thread count is greater than the hardware thread + count, validate the “target” has a corresponding hardware thread else + return H_Not_Available. + + + + Validate the “priority” parameter is a valid priority and not in + listed in the + “ibm,plat-res-int-priorities” + property else return H_P3. + + + + Load R4 with the ESn page from the Event Notification Descriptor + Table associated with “target” and “priority”. + + + + Load R5 with the page size of the ESn page. + + + + Return H_Success. + + + +
+ +
+ H_INT_SET_QUEUE_CONFIG + + The H_INT_SET_QUEUE_CONFIG hcall() is used to set or reset an EQ for a + given “target” and “priority”. It is also used to set the notification + config associated with the EQ. An EQ size of 0 is used to reset the EQ + config for a given target and priority. If resetting the EQ config, the + END associated with the given “target” and “priority” will be changed to + disable queuing. + + Upon return from the hcall(), no additional interrupts will be directed + to the old EQ (if one was set). The old EQ (if one was set) should be + investigated for interrupts that occurred prior to or during the hcall(). + + + Syntax: + + + + + Parameters: + + + + “flags”: + + + Bits 0-62: Reserved + + + + Bit 63: Unconditional Notify (n) per the XIVE spec + + + + + + + “target”: is per + “ibm,ppc-interrupt-server#s” or + “ibm,ppc-interrupt-gserver#s” + + + + “priority”: is valid priority not in the + “ibm,plat-res-int-priorities” + + + + “eventQueue”: The logical real address of the start of the EQ + + + + “eventQueueSize”: The power of 2 EQ size per + “ibm,xive-eq-sizes” + + + + + + Return Values: + + None + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “target” parameter per the list of threads allocated + the calling partition else return H_P2. + + + + If the partition thread count is greater than the hardware thread + count, validate the “target” has a corresponding hardware thread else + return H_Not_Available. + + + + Validate the “priority” parameter is a valid priority and not in listed in the + “ibm,plat-res-int-priorities” + property else return H_P3. + + + + Validate the “eventQueueSize” parameter per + “ibm,xive-eq-sizes”, + else return H_P5. + + + + Validate that if “eventQueueSize” is not 0 then the calling partition owns the logical real address in “eventQueue” for the length of “eventQueueSize” else return H_P4. + + + + If “Unconditional Notify” = 0 notification is conditioned by the + notification page from H_INT_GET_QUEUE_INFO. + + + + If the “eventQueueSize” is not 0 then: + + + The memory pointed to by “eventQueue” must be zeroed by the OS. + + + + The generation bit for the EQ will start at 1. + + + + The EQ page offset counter will start at 0. + + + + The EQ config will be set to “eventQueue” and “eventQueueSize”. + + + + + + + If the “eventQueueSize” is 0 then: + + + The EQ config will be reset. + + + + Queuing of interrupts will be disabled. + + + + + + + Issue syncs required to ensure all in-flight interrupts are complete. + + + + Return H_Success. + + + +
+ +
+ H_INT_GET_QUEUE_CONFIG + + The H_INT_GET_QUEUE_CONFIG hcall() is used to get an EQ and the EQ size + for a given target and priority. If requested via the “Debug” flag, + this will also return the current generation value and event queue offset. + + + Syntax: + + + + + Parameters: + + + + "flags": + + + Bits 0-62: Reserved + + + + Bit 63: Debug: Return debug data + + + + + + + “target”: is per + “ibm,ppc-interrupt-server#s” or + “ibm,ppc-interrupt-gserver#s” + + + + “priority”: is valid priority not in the + “ibm,plat-res-int-priorities” + + + + + + Return Values: + + + + R4: “flags”: + + + Bit 0-62: Reserved + + + + Bit 62: The value of Event Queue Generation Number (g) per + the XIVE spec if “Debug” = 1 + + + + Bit 63: The value of Unconditional Notify (n) per the XIVE spec + + + + + + + R5: The logical real address of the start of the EQ + + + + R6: The power of 2 EQ size per + “ibm,xive-eq-sizes” + + + + R7: The value of Event Queue Offset Counter per XIVE spec if + “Debug” = 1, else 0 + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “target” parameter per the list of threads + allocated the calling partition else return H_P2. + + + + If the partition thread count is greater than the hardware thread + count, validate the “target” has a corresponding hardware thread + else return H_Not_Available. + + + + Validate the “priority” parameter is a valid priority and not in + listed in the + “ibm,plat-res-int-priorities” + property else return H_P3. + + + + Load R4 with the return flags, setting the reserved bits to 0. + + + + Load R5 with the logical real address of the EQ associated with + “target” and “priority”. Set to -1 if no EQ has + been specified + + + + Load R6 with the size of the EQ associated with the “target” and + “priority”. Set to 0 if no EQ has been specified. + + + + If “Debug” = 1 + + + Load the event queue generation number into the return flags + + + + Load R7 with the event queue offset counter + + + + Use the appropriate hardware facility to get an atomic + view of the generation number and offset counter. + + + + + + + Return H_Success. + + + +
+ +
+ H_INT_SET_OS_REPORTING_LINE + + The H_INT_SET_OS_REPORTING_LINE hcall() is used to set the reporting + cache line pair for the calling thread. The reporting cache lines will + contain the OS interrupt context when the OS issues a CI store byte to + @TIMA+0xC10 8 to acknowledge the OS interrupt. The reporting cache lines + can be reset by inputting -1 in “reportingLine”. Issuing the CI store byte + without reporting cache lines registered will result in the data not being + accessible to the OS. + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + “reportingLine”: The logical real address of the reporting cache line pair + + + + + + Return Values: + + None + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + If the partition thread count is greater than the hardware thread count, + validate the “target” has a corresponding hardware thread else return + H_Not_Available. + + + + If the “reportingLine” is not -1 + + + Validate the calling partition owns the logical real address + in “reportingLine” for two cache lines else return H_P2. + + + + Validate that the “reportingLine” is cached aligned, else + return H_P2. + + + + Set the “reportingLine” in the NVT associated with the input + “target”. + + + + + + + If the “reportingLine” is -1 + + + Reset the NVT’s reporting line. + + + + + + + Return H_Success. + + + +
+ +
+ H_INT_GET_OS_REPORTING_LINE + + The H_INT_GET_OS_REPORTING_LINE hcall() is used to get the logical real + address of the reporting cache line pair set for the input “target”. If no + reporting cache line pair has been set, -1 is returned. + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + “target”: is per + “ibm,ppc-interrupt-server#s” + + + + + + Return Values: + + + + R4: The logical real address of the reporting line if set, else -1 + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “target” parameter per the list of threads allocated + the calling partition else return H_P2. + + + + Validate the thread indicated by “target” is online else + return H_Not_Available. + + + + If the partition thread count is greater than the hardware + thread count, validate the “target” has a corresponding hardware + thread else return H_Not_Available. + + + + Load R4 with the logical real address of the reporting line + associated with “target”. Load R4 with -1 if no reporting line has been set. + + + + Return H_Success. + + + +
+ +
+ H_INT_ESB + + + + + Syntax: + + + + + Parameters: + + + + “flags”: + + + bits 0-62: Reserved + + + + bit 63: Store: Store=1, store operation, else load operation + + + + + + + “lisn” is per + “interrupts”, + “interrupt-map”, or + “ibm,xive-lisn-ranges” properties, or as returned by the + ibm,query-interrupt-source-number + RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall + + + + “esbOffset” is the offset into the ESB management page for the load or store operation + + + + “storeData” is the data to write for a store operation + + + + + + Return Values: + + + + R4: The value of the load if load operation, else -1 + + + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “lisn” parameter per the list of interrupt sources + allocated to the calling partition else return H_P2. + + + + Validate the “esbOffset” parameter is valid per the XIVE Spec + else return H_P3. + + + + If bit 63 of flags is 0 + + + Issue the load operation to the “esbOffset” of the ESB + management page associated with “lisn”. + + + + Load R4 with the results of the load operation. + + + + + + + If bit 63 of flags is 1 + + + Issue the store operation to the “esbOffset” of the ESB + management page associated with “lisn”, storing “storeData”. + + + + Load R4 with -1. + + + + + + + Return H_Success. + + + +
+ +
+ H_INT_SYNC + + The H_INT_SYNC hcall() is used to issue hardware syncs that will + ensure any in flight events for the input lisn are in the event queue. + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + “lisn” is per + “interrupts”, + “interrupt-map”, or + “ibm,xive-lisn-ranges” properties, or as returned by the + ibm,query-interrupt-source-number + RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall + + + + + + Return Values: + + None + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Verify that a H_INT_RESET is not in progress else return H_State. + + + + Validate the “lisn” parameter per the list of interrupt sources + allocated to the calling partition else return H_P2. + + + + Perform the appropriate hardware syncs to ensure any in flight + events for the input “lisn” are in the event queue. + + + + Return H_Success. + + + +
+ +
+ H_INT_RESET + + The H_INT_RESET hcall() is used to reset all of the partition’s interrupt + exploitation structures to their initial state. This means losing all p + reviously set interrupt state set via H_INT_SET_SOURCE_CONFIG and + H_INT_SET_QUEUE_CONFIG. + + + + Syntax: + + + + + Parameters: + + + + “flags”: bits 0-63 Reserved + + + + + + Return Values: + + None + + + + Semantics: + + + + Verify that no reserved flag bits are on else return H_Parameter. + + + + Block all other exploitation hcalls (they all will return H_STATE + if called while H_INT_RESET is in progress). + + + + Verify that no other threads are currently in the middle of an + H_INT_RESET for this partition else return H_STATE + + + + Reset the following: + + + All EAs + + + + All ESB states + + + + All ENDs + + + Specifically, including clearing out its EQ pointer and size + + + + + + + + + + All OS Reporting LinesUnblock all other exploitation hcalls when finished. + + + + Return H_Success. + + + +