diff --git a/common/app_EOD.xml b/LoPAR/app_EOD.xml similarity index 100% rename from common/app_EOD.xml rename to LoPAR/app_EOD.xml diff --git a/Platform/app_bibliography.xml b/LoPAR/app_bibliography.xml similarity index 75% rename from Platform/app_bibliography.xml rename to LoPAR/app_bibliography.xml index 4d830bf..dce18da 100644 --- a/Platform/app_bibliography.xml +++ b/LoPAR/app_bibliography.xml @@ -1,7 +1,7 @@ Bibliography - This section lists documents which were referenced in this specification or which provide - additional information, and some useful information for obtaining these documents. Referenced - documents are listed below. When any of the following standards are superseded by an approved + This section lists documents which were referenced in this specification or which provide + additional information, and some useful information for obtaining these documents. Referenced + documents are listed below. When any of the following standards are superseded by an approved revision, the revision shall apply. - + - + - Linux on Power Architecture Reference: Device Tree - Linux on Power Architecture Reference: Error Recovery and Logging - Linux on Power Architecture Reference: Virtualization - Linux on Power Architecture Reference: Runtime Abstraction Services (RTAS) - Power ISAPower ISA - + - - IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware: + IEEE 1275, IEEE Standard for Boot (Initialization Configuration) Firmware: Core Requirements and Practices IEEE part number DS02683, ISBN 1-55937-426-8 - + - Core Errata, IEEE P1275.7/D4 - + - - Open Firmware Recommended Practice:OBP-TFTP + Open Firmware Recommended Practice:OBP-TFTP Extension - + - - Open Firmware Recommended Practice: Device + Open Firmware Recommended Practice: Device Support Extensions - + - - PCI Bus binding to: IEEE Std 1275-1994, Standard + PCI Bus binding to: IEEE Std 1275-1994, Standard for Boot (Initialization, Configuration) Firmware - + - - Open Firmware: Recommended Practice - Interrupt + Open Firmware: Recommended Practice - Interrupt Mapping - + - - Open Firmware: Recommended Practice - Forth Source + Open Firmware: Recommended Practice - Forth Source and FCode Image Support, Version 1.0 - + - - Open Firmware: Recommended Practice - Interrupt + Open Firmware: Recommended Practice - Interrupt Mapping, Version 1.0 - + - - Open Firmware: Recommended Practice - TFTP Booting + Open Firmware: Recommended Practice - TFTP Booting Extensions, Version 0.8 - + - - Open Firmware: Recommended Practice - + Open Firmware: Recommended Practice - Interposition, Version 0.2 - + - MS-DOS Programmer's Reference Published by Microsoft - + - - Peering Inside the PE: A Tour of the Win32 Portable + Peering Inside the PE: A Tour of the Win32 Portable Executable File Format Found in the March, 1994 issue of Microsoft Systems Journal - + - - ISO-9660, Information processing -- Volume and + ISO-9660, Information processing -- Volume and file structure of CD-ROM for information interchange Published by International Organization for Standardization - + - - System V Application Binary Interface, PowerPC + System V Application Binary Interface, PowerPC Processor Supplement By Sunsoft - + - ISO Standard 8879:1986, Information Processing -- Text and Office Systems -- Standard Generalized Markup Language (SGML) - + - - IEEE 996, A Standard for an Extended Personal Computer + IEEE 996, A Standard for an Extended Personal Computer Back Plane Bus - + - PCI Local Bus Specification - All designers are responsible for assuring that they use the most current version of this document - at the time that they design conventional PCI related components or platforms. See the PCI SIG website + All designers are responsible for assuring that they use the most current version of this document + at the time that they design conventional PCI related components or platforms. See the PCI SIG website for the most current version of this document. - + - PCI-to-PCI Bridge Architecture Specification - All designers are responsible for assuring that they use the most current version of this document - at the time that they design conventional PCI related components or platforms. See the + All designers are responsible for assuring that they use the most current version of this document + at the time that they design conventional PCI related components or platforms. See the PCI SIG website for the most current version of this document. - + - - PCI Standard Hot-Plug Controller and Subsystem + PCI Standard Hot-Plug Controller and Subsystem Specification - + - PCI-X Protocol Addendum to the PCI Local Bus Specification - All designers are responsible for assuring that they use the most current version of this document at - the time that they design PCI-X related components or platforms. See the PCI SIG website for the most + All designers are responsible for assuring that they use the most current version of this document at + the time that they design PCI-X related components or platforms. See the PCI SIG website for the most current version of this document. - + - PCI Express Base Specification - All designers are responsible for assuring that they use the most current version of this document - at the time that they design PCI Express related components or platforms. See the PCI SIG website for + All designers are responsible for assuring that they use the most current version of this document + at the time that they design PCI Express related components or platforms. See the PCI SIG website for the most current version of this document. - + - PCI Express to PCI/PCI-X Bridge Specification - All designers are responsible for assuring that they use the most current version of this document at the - time that they design PCI Express related components or platforms. See the PCI SIG website for the most current + All designers are responsible for assuring that they use the most current version of this document at the + time that they design PCI Express related components or platforms. See the PCI SIG website for the most current version of this document. - + - - System Management BIOS (SMBIOS) Reference + System Management BIOS (SMBIOS) Reference Specification - + (List Number Reserved for Compatibility) - + (List Number Reserved for Compatibility) - + (List Number Reserved for Compatibility) - + - - IBM RS/6000® Division, Product Topology Data System, + IBM RS/6000® Division, Product Topology Data System, Product Development Guide Version 2.1 - + - Single Root I/O Virtualization and Sharing Specification - All designers are responsible for assuring that they use the most current version of this document at - the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website + All designers are responsible for assuring that they use the most current version of this document at + the time that they design PCI Express SR-IOV related components or platforms. See the PCI SIG website for the most current version of this document. - + - Multi-Root I/O Virtualization and Sharing Specification - All designers are responsible for assuring that they use the most current version of this document at the - time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the + All designers are responsible for assuring that they use the most current version of this document at the + time that they design PCI Express MR-IOV related components or platforms. See the PCI SIG website for the most current version of this document. - + - diff --git a/Error Handling/app_capi_error_handling.xml b/LoPAR/app_capi_error_handling.xml similarity index 100% rename from Error Handling/app_capi_error_handling.xml rename to LoPAR/app_capi_error_handling.xml diff --git a/RTAS/ch_cmo_def.xml b/LoPAR/app_cmo_def.xml similarity index 94% rename from RTAS/ch_cmo_def.xml rename to LoPAR/app_cmo_def.xml index 3808f8b..6dd2806 100644 --- a/RTAS/ch_cmo_def.xml +++ b/LoPAR/app_cmo_def.xml @@ -1,7 +1,7 @@ - - + CMO Characteristics Definitions - - This chapter defines the string that is returned by the + + This appendix defines the string that is returned by the ibm,get-system-parameter RTAS call when the parameter - token value of 44 (CMO Characteristics) is specified on the - ibm,get-system-parameter RTAS call as per + token value of 44 (CMO Characteristics) is specified on the + ibm,get-system-parameter RTAS call as per . - +
CMO Terms The LoPAR Cooperative Memory Over-commitment option (CMO) defines - terms as presented in + terms as presented in . @@ -89,14 +89,14 @@
- +
Key Words And Values defines the key words and the associated legal values that will be returned in the ASCII NULL terminated string when the parameter token value of 44 (CMO characteristics) is - specified on the + specified on the ibm,get-system-parameter RTAS call. The key word and value is separated by an ASCII equal (“=”). Each key word, value pair is delimited by an ASCII comma in the string. The numerical @@ -170,4 +170,4 @@
- + diff --git a/Platform/app_eeh_handling.xml b/LoPAR/app_eeh_handling.xml similarity index 100% rename from Platform/app_eeh_handling.xml rename to LoPAR/app_eeh_handling.xml diff --git a/Error Handling/app_fault_v_errorlog.xml b/LoPAR/app_fault_v_errorlog.xml similarity index 100% rename from Error Handling/app_fault_v_errorlog.xml rename to LoPAR/app_fault_v_errorlog.xml diff --git a/RTAS/ch_firmware_dump.xml b/LoPAR/app_firmware_dump.xml similarity index 99% rename from RTAS/ch_firmware_dump.xml rename to LoPAR/app_firmware_dump.xml index 247f8cb..0a65f42 100644 --- a/RTAS/ch_firmware_dump.xml +++ b/LoPAR/app_firmware_dump.xml @@ -1,7 +1,7 @@ - Firmware Assisted Dump Data Format - This Appendix documents the dump data format, in support of the + This appendix documents the dump data format, in support of the Configure Platform Assisted Kernel Dump option in . - +
Register Save Area The register save area is an area in the partition’s memory used to preserve the registers for the active CPUs during a firmware assisted dump. The location and size of this area is specified by the partition when firmware assisted dumpwhen it registers for firmware - assisted dump using the . + assisted dump using the . The minimum size will be sent to the partition in the PFDS KDUMP node. The register save is a semi-free format list of registers for each @@ -43,8 +43,8 @@ Notes: - - + + Only CPUs that are online at the start of the Firmware Assisted Dump will have their register data saved. @@ -59,16 +59,16 @@ required to be in any specific order (To make debug easier they will most likely be placed in ascending ASCII identifier order) - + - If the CPU is in a Transactional Memory operating mode such - that there is a valid register check point, the contents of that register - checkpoint is included with register identifiers starting with “X-”, see + If the CPU is in a Transactional Memory operating mode such + that there is a valid register check point, the contents of that register + checkpoint is included with register identifiers starting with “X-”, see , else the checkpoint registers are not included. - - + + Register Save Area Format @@ -6278,5 +6278,5 @@ is up to the user of the save area to sort the data. - - + + diff --git a/Platform/app_glossary.xml b/LoPAR/app_glossary.xml similarity index 100% rename from Platform/app_glossary.xml rename to LoPAR/app_glossary.xml diff --git a/DeviceTree/ch_devtree_pa.xml b/LoPAR/app_pa_processor_binding.xml similarity index 93% rename from DeviceTree/ch_devtree_pa.xml rename to LoPAR/app_pa_processor_binding.xml index b76b4b4..3f10b2c 100644 --- a/DeviceTree/ch_devtree_pa.xml +++ b/LoPAR/app_pa_processor_binding.xml @@ -1,7 +1,7 @@ - - Processor Architecture Binding - + PA Processor Binding + +
+ Purpose of this Binding + + This appendix specifies the application of OF to a PA Processor (which covers + all PowerPC processors and their suc- cessors), including requirements and + practices to support unique firmware specific to a PA Processor. The core + requirements and practices specified by OF must be augmented by processor-specific + requirements to form a complete specification for the firmware implementation + for a PA processor. This appendix establishes such additional requirements + pertaining to the processor and the support required by OF. +
+ +
+ Overview + + This appendix specifies the application of + + to computer systems that use the PA instruction set, including + instruction-set-specific requirements and practices for debugging, client + program interface and data formats. An implementation of OF for PA shall + implement the core requirements as defined in + and the PA-specific extensions + described in this binding. + + This appendix addresses + . The descriptions that follow, + and the relevant sections describing translation features for this binding, + assume that the system’s PA processor(s) implement the entire PA + (that is, all books of + ). Some processors may implement + different Book II-III features; such processors may need a variant of this + binding describing the differences to the mapping functions, etc. + +
+ + +
Data Formats and Representations - - The cell size shall be 32 bits. Number ranges for - n, + + The cell size shall be 32 bits. Number ranges for + n, u, and other cell-sized items are consistent with 32-bit, two's-complement number representation. - The required alignment for items accessed with + The required alignment for items accessed with a-addr addresses shall be four-byte aligned (i.e., a multiple of 4). - Each operation involving a + Each operation involving a qaddr address shall be performed with a single 32-bit - access to the addressed location; similarly, each + access to the addressed location; similarly, each waddr access shall be performed with a single 16-bit - access. This implies four-byte alignment for - qaddrs and two-byte alignment for + access. This implies four-byte alignment for + qaddrs and two-byte alignment for waddrs. - +
- +
Memory Management - +
PA Address Translation Model - + This section describes the model that is used for co-existence of OF and client programs (i.e., OSs) with respect to address translation. The following overview of translation is provided so that the issues relevant to OF for the PA can be discussed. Details that are not - relevant to OF issues (e.g., protection) are not described in detail; + relevant to OF issues (e.g., protection) are not described in detail; , particularly Book III, should be consulted for the details. For the scope of this section, terms will - be used as defined in + be used as defined in . - +
Translation requirements - + The default access mode of storage for load and stores (i.e., with - translation disabled -- referred to as + translation disabled -- referred to as Real-Mode) within the PA assumes that caches are enabled (in copy-back mode). In order to perform access to I/O device registers, the access mode must be set to Cache-Inhibited, Guarded by establishing a translation with this mode and enabling translation. Thus, even though most of a client program and/or OF can run with translation disabled, it must be enabled when performing I/O. - +
- +
Segmented Address Translation - + Note: The use of the term Virtual Address in this section refers to the PA definition, while the rest of the document uses @@ -83,7 +121,7 @@ Note: The following description of PA address translation is only one of several translation modes available and is - given for reference only. See + given for reference only. See for complete details. An Effective Address (EA) of a PA processor is 64(32) bits wide. Each EA is translated into an 80(52)-bit Virtual Address (VA) by @@ -117,12 +155,12 @@ HTAB might be too small to contain all of the currently valid translations. This introduces a level of complexity in the use of address translation by OF, as discussed below. - +
- +
Block Address Translation - + To further reduce the translation overhead for contiguous regions of virtual and real address spaces (e.g., a frame buffer, or all of real memory), the Block Address Translation (BAT) mechanism is also supported @@ -149,20 +187,20 @@ Note: Block Address Translation is a deprecated translation mode of the PA. This description is retained here for - historical reference. See + historical reference. See for details on all supported addressing mechanisms. - +
- +
Open Firmware’s use of memory - + OF shall use the memory resources within the space indicated by the - - real-base, - real-size, + + real-base, + real-size, virt-base, and virt-size Configuration Variables defined for the PA. As described in the applicable platform binding, a mechanism is defined @@ -173,20 +211,20 @@ and/or virtual address space usage by means of its program header. When OF loads the client program, it inspects the program header, and if its current usage of physical memory or virtual address space conflicts with - that specified in the program header, OF shall set the - real-base, - real-size, - virt-base, and + that specified in the program header, OF shall set the + real-base, + real-size, + virt-base, and virt-size to the configuration variables as specified - in the header and restart itself. - Real-base, - real-size, - virt-base, and + in the header and restart itself. + Real-base, + real-size, + virt-base, and virt-size may be specified as -1, in which case the firmware is permitted to choose appropriate values for the variables specified as -1. - If the values of the - real-size and/or + If the values of the + real-size and/or virt-size configuration variables do not provide sufficient memory and/or virtual address space for the firmware's own use, then the firmware shall not attempt to load a client program and the @@ -197,26 +235,26 @@ this exposure by setting size to -1 and allowing OF to choose the size. A PA OF binding shall support two different addressing models, - depending upon the setting of the + depending upon the setting of the real-mode? Configuration Variable. This variable - indicates the OF addressing mode that a client program expects; - false (0) indicates Virtual-Mode, - true (-1) indicates Real-Mode; the default value of + indicates the OF addressing mode that a client program expects; + false (0) indicates Virtual-Mode, + true (-1) indicates Real-Mode; the default value of real-mode? is implementation dependent. - The management of - real-mode? is analogous to + The management of + real-mode? is analogous to little-endian?. OF determines its addressing mode - using the value of - real-mode?. If the current state of + using the value of + real-mode?. If the current state of real-mode? (and hence, the current state of OF) is - incorrect, it shall set + incorrect, it shall set real-mode? appropriately and reset itself, possibly - by executing + by executing reset-all. Memory that cannot be allocated for general purpose use, for example physical memory on LoPAR systems used for interrupt vectors and implementation specific areas, shall not appear in the “ - available ” property of the + available ” property of the memory node. A Client Program that needs to use such memory for its architected purpose must not claim that area prior to use. @@ -225,72 +263,72 @@ describe the assumptions that OF makes about the state and control of the system in regard to OF’s use of system resources for three OF interfaces (e.g. Device, User and Client interfaces). - +
Real-Mode - - In Real-Mode (when - real-mode? is + + In Real-Mode (when + real-mode? is true), the use of address translations by OF and its client are independent. Either they do not use translation, or their translations are private; they do not share any translations. All interfaces between the two must pass the real address of the data. Any - data structure shared by OF and its client that refers to - virt addresses in + data structure shared by OF and its client that refers to + virt addresses in , or this binding, must be real addresses. Note: In particular, that the address of the Client interface handler, that is passed to the client, has to be a real address. - The Configuration Variables - real-base and + The Configuration Variables + real-base and real-size should indicate the physical memory base and size in which OF must locate itself. In Real-Mode, the Configuration - Variables + Variables virt-base and virt-size do not have meaning and should be set to -1. - +
- +
Virtual-Mode - - When - real-mode? is - false, OF shall configure itself to run in + + When + real-mode? is + false, OF shall configure itself to run in Virtual-Mode. In Virtual-Mode, OF and its client will share a single virtual address space. This binding provides interfaces to allow OF and its client to ensure that this single virtual address model can be maintained. - The Configuration Variables + The Configuration Variables virt-base and virt-size should indicate the virtual address space - base address and size that OF should use. The Configuration Variables - real-base and + base address and size that OF should use. The Configuration Variables + real-base and real-size should indicate the physical memory base and size in which OF must locate itself. - +
- +
Device Interface (Real-Mode) - + While OF is performing system initialization and probing functions, it establishes and maintains its own translations. In particular, it maintains its own Page Tables (and/or BAT entries) and handles any DSI/ISI interrupts itself. - Note: In Real-Mode, all translations will be + Note: In Real-Mode, all translations will be virt=real; the primary reason for translation is to allow appropriate I/O accesses. - +
- +
Device Interface (Virtual-Mode) - + OF will establish its own translation environment, handling DSI/ISI interrupts as in the Real-Mode case. However, this environment will, in general, contain translations in which virtual addresses do not equal @@ -302,21 +340,21 @@ device-tree, etc.), their translations must be preserved until the client OS decides that it no longer requires the services of OF.
- +
Client Interface (Real-Mode) - + In Real-Mode, addresses of client data are real.; the client must ensure that all data areas referred to across the Client Interface are valid real addresses. This may require moving data to meet any - requirements for contiguous storage areas (e.g., for + requirements for contiguous storage areas (e.g., for read/write calls). Translation shall be disabled before the client interface call is made. OF will typically have to maintain its translations in order to perform I/O. Since the client may be running with translation enabled (except for the Client interface call), OF shall save the state of all relevant translation resources (e.g., SDR1, BATs) and restore them before - returning to the client. Likewise, it + returning to the client. Likewise, it may take over interrupts for its own use (e.g., for doing “lazy” allocation of BATs); it shall preserve the state of any interrupt vectors for its client. @@ -336,15 +374,15 @@ assist callbacks. OF shall use the client program's real-mode physical memory management assist callbacks to allocate physical memory after the client program has assumed physical memory management. - In Real-Mode, + In Real-Mode, claim methods shall not allocate more pages than are necessary to satisfy the request. - +
- +
Client Interface (Virtual-Mode) - + Client interface calls are essentially “subroutine” calls to OF. Hence, the client interface executes in the environment of its client, including any translations that the OS has established. E.g., @@ -360,132 +398,132 @@ these OF translations if it takes over the virtual memory management function. In addition to using existing translations, the Client Interface - might require the establishment of new translations (e.g., due to - map-in calls during + might require the establishment of new translations (e.g., due to + map-in calls during open time), or the removal of old translations (e.g., - during - map-out calls during + during + map-out calls during close time). Since this requires altering the Client’s translation resources (e.g., Page Tables), possibly handling spill conditions, OF cannot know how to perform these updates. - Hence, there shall be + Hence, there shall be callback services provided by the client for use by - OF for such actions; see + OF for such actions; see . In order to let clients (i.e., target OSs) know where OF lives in the address space, the following rules shall be followed by an OF implementation for the PA and by client programs. OF: - - + + OF shall maintain its “translations” - “mmu”-node property (see + “mmu”-node property (see ) - + - OF’s - claim methods shall not allocate more pages + OF’s + claim methods shall not allocate more pages than are necessary to satisfy the request. - + - When a client executes + When a client executes set-callback, OF shall attempt to invoke the “translate” callback. If the translate callback is implemented, OF shall cease use of address translation hardware, instead using the client callbacks for changes to address translation. - - - The - exit service must continue to work after a + + + The + exit service must continue to work after a set-callback that takes over address translation. This implies that OF takes responsibility for address translation - hardware upon + hardware upon exit and must maintain internal information about translations that it requests of the client. Client Programs: - - + + Client programs that take control of the management of address translation hardware and expect to be able to subsequently invoke OF client services must provide callbacks to assist OF in address - translation (see + translation (see ). - + A client program shall not directly manipulate any address translation hardware before it either a) ceases to invoke OF client - services or b) issues a + services or b) issues a set-callback to install the “translate” callback. - - + + Note: The intended sequence is that a client program will first issue a set-callback and then take control of address translation hardware. Address translation hardware includes BAT entries, page table, segment registers, Machine State Register and the interrupt vectors relating to translation faults. - +
- +
User Interface (Real-Mode) - + In Real-Mode, OF regains total control of the system. As with the Client interface in Real-Mode, it should save the state of the translation resources (including interrupt vectors) upon entry and should restore them upon exit. - +
- +
User Interface (Virtual-Mode) - + When the User interface is invoked, OF is responsible for managing the machine. Therefore, it will take over control of any relevant interrupt vectors for its own handling. In particular, it will take over DSI/ISI handling in order to report errors to the user for bad addresses, protection violations, etc. However, as described above, one source of - DSI/ISI may simply be HTAB spills. As with the case of - map-in and + DSI/ISI may simply be HTAB spills. As with the case of + map-in and map-out calls, the User interface cannot know how to handle such spill conditions, itself, or even if this is, in fact, a spill versus a bad address. - Hence, this binding defines + Hence, this binding defines callback services that the client provides for use by - OF; see + OF; see . - +
- +
- +
Properties This section describes the standard properties of a PA OF implementation. - +
CPU properties - +
The Device Tree - + OF requires that the multiple instances of any device that appears more than once in the device tree must be distinguishable by means of - their - “reg” properties. The + their + “reg” properties. The “reg” property must express the address of each node relative to its parent bus. Furthermore, the core specification says that the root node of the device tree usually @@ -498,22 +536,22 @@ “cpus”. The “cpus” node shall have one child node of device_type “cpu” for each processor. - +
- +
Physical Address Formats and Representations for CPU Nodes - + - +
Numerical Representation The numerical representation of a processor’s “address” in a LoPAR system shall consist of one cell, encoded as follows (Bit# 0 refers to the least significant bit) : - +
Numerical Representation of a Processor’s “address” @@ -575,44 +613,44 @@
- where: + where: pppppppp is an 8-bit integer representing the interprocessor interrupt identifier used by the platform. - +
- +
Text Representation - + The text representation of a processor’s - “address” shall be an ASCII hexadecimal number in the range + “address” shall be an ASCII hexadecimal number in the range 0...FF. Conversion of the hexadecimal number from text representation to numeric representation shall be case insensitive, and leading zeros shall be permitted but not required. Conversion from numeric representation to text representation shall - use the lower case forms of the hexadecimal digits in the range + use the lower case forms of the hexadecimal digits in the range a..f, suppressing leading zeros. - +
- +
Unit Address Representation - + A processor’s “unit-number” (i.e. the first - component of its + component of its “reg” value) is the interprocessor interrupt destination identifier used by the platform. For a uni-processor platform, the “unit-number” shall be zero. - +
- + - +
CPUS Node Properties - + The following properties shall be created within the “cpus” node. @@ -626,17 +664,17 @@ cpus ” node). prop-encoded-array: Integer constant 1, encoded as with encode-int. - The value of + The value of “#address-cells” for the - “cpus” node shall be + “cpus” node shall be 1. - + “#size-cells” - Standard + Standard property name to define the number of cells necessary to represent the length of a physical address range. prop-encoded-array: Integer constant 0, encoded as @@ -648,16 +686,16 @@ - +
- +
CPU Node Properties - + For each CPU in the system, a cpu-node shall be defined as a child - of + of “cpus”. The following properties apply to - each of these nodes. The + each of these nodes. The cpus node shall not have “ reg ” or “ ranges ” properties. In general, properties in @@ -665,92 +703,92 @@ that convey the presence of instructions, presence of registers, or location of resources) to the processor are preserved by the device tree once presented upon boot. For a list of properties that may change before - a reboot, see + a reboot, see . “name” - Standard property name. The value of this property - shall be of the form: “PowerPC,<name>”, where <name> + Standard property name. The value of this property + shall be of the form: “PowerPC,<name>”, where <name> is the name of the processor chip which may be displayed to the user. - <name> + <name> shall not contain underscores. - + “device_type” - Standard property name. The value of this - property for CPU nodes shall be + Standard property name. The value of this + property for CPU nodes shall be “cpu”. - + “reg” Standard proper name to define a cpu node’s unit-address. - prop-encoded-array: an integer encoded as with + prop-encoded-array: an integer encoded as with encode-int. - For a cpu node, the first and only value of the + For a cpu node, the first and only value of the “reg” property shall be the number of the per-processor interrupt line assigned to the processor represented by the - node. For a uni-processor platform, the value of the + node. For a uni-processor platform, the value of the “reg” property shall be zero. - + “status” - Standard property name. The value of the is + Standard property name. The value of the is property shall be one of the following string values: - - + + “okay” for a good processor. - + “fail” for a processor that fails during power-on testing. - + - “fail-offline” - for a processor that has been automatically deconfigured because of previous + “fail-offline” + for a processor that has been automatically deconfigured because of previous failures. - + - “disabled” + “disabled” for a processor that has been manually deconfigured. - + - + “cpu-version” property name: Represents the processor type. - prop-encoded-value: The value, encoded as with - encode-int, + prop-encoded-value: The value, encoded as with + encode-int, shall be either the value obtained by reading the Processor Version Register of the processor described by this - node, or the logical processor version as given in + node, or the logical processor version as given in . The first byte of the logical processor version value shall be 0x0F. The values of the “Logical - Processor Version” column of + Processor Version” column of indicate that the processor provides the base support described by that version of the architecture. The presence and value of all optional and implementation dependent features and facilities are described by their corresponding properties. - + Logical Processor Version Values @@ -827,16 +865,16 @@
- + “clock-frequency” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the internal processor speed (in hertz) of this node. - + “ibm,extended-clock-frequency” @@ -844,28 +882,28 @@ processor speed in hertz of this node. This property allows the encoding of multi-giga-hertz quantities. prop-encoded-array: Consisting of the low order 32 - bits of two cells (freq-hi, freq-lo) each encoded as with - encode-int, such that - their combined value is (the low order 32 bits of freq-hi || the low order + bits of two cells (freq-hi, freq-lo) each encoded as with + encode-int, such that + their combined value is (the low order 32 bits of freq-hi || the low order 32 bits of freq-lo). - + “timebase-frequency” - Standard property name, encoded as with - encode-int, + Standard property name, encoded as with + encode-int, that represents the rate (in hertz) at which the PA TimeBase and Decrementer registers are updated. - Note: The 601 PowerPC + Note: The 601 PowerPC processor does not have a timebase frequency, therefore on a 601 PowerPC processor the value reported in this property shall be 1 billion (1 x 109) which represents the logical rate of the real time clock. - + “ibm,extended-timebase-frequency” @@ -873,30 +911,30 @@ hertz at which the PA TimeBase and Decrementer registers are updated. This property allows the encoding of multi-giga-hertz quantities. prop-encoded-array: Consisting of the low order 32 - bits of two cells (freq-hi, freq-lo) each encoded as with - encode-int, such that their combined + bits of two cells (freq-hi, freq-lo) each encoded as with + encode-int, such that their combined value is (the low order 32 bits of freq-hi || the low order 32 bits of freq-lo). - Note: The - “ibm,extended-timebase-frequency” - property will be deprecated from the architecture due to the emergence of the + Note: The + “ibm,extended-timebase-frequency” + property will be deprecated from the architecture due to the emergence of the “ibm,nominal-tbf” property and the lack - of a need for a two cell version of the + of a need for a two cell version of the “timebase-frequency” property. - Implementations should not provide the + Implementations should not provide the “ibm,extended-timebase-frequency” property. - + “ibm,nominal-tbf” - property name: Property, encoded as with - encode-int, + property name: Property, encoded as with + encode-int, that represents the design nominal timebase frequency (in hertz). - + “ibm,tbu40-offset” @@ -909,7 +947,7 @@ unsigned, binary value. - + “64-bit” @@ -920,7 +958,7 @@ is a 32 bit implementation of the PA - + “64-bit-virtual-address” @@ -931,14 +969,14 @@ indicates that the PA processor defined by this CPU node supports the full 80-bit virtual address defined by the PA. This property is only valid for 64-bit implementations. - Note: The - “64-bit-virtual-address” + Note: The + “64-bit-virtual-address” will be deprecated from the architecture. Implementations should not provide this property. - + “603-translation” @@ -951,7 +989,7 @@ TLBs. - + “603-power-management” @@ -963,17 +1001,17 @@ processor defined power management states. - + “bus-frequency” - Standard property name, encoded as with - encode-int, + Standard property name, encoded as with + encode-int, that represents the speed (in hertz) of this processor’s bus. - + “ibm,extended-bus-frequency” @@ -981,13 +1019,13 @@ hertz of this processor’s bus. This property allows the encoding of multi-giga-hertz quantities. prop-encoded-array: Consisting of the low order 32 - bits of two cells (freq-hi, freq-lo) each encoded as with - encode-int, + bits of two cells (freq-hi, freq-lo) each encoded as with + encode-int, such that their combined value is (the low order 32 bits of freq-hi || the low order 32 bits of freq-lo). - + “32-64-bridge” @@ -995,13 +1033,13 @@ This property, if present, indicates that the PA processor defined by this CPU node implements the “Bridge Facilities and Instructions for 64-bit Implementations” as described in an appendix of Book III - of + of . The absence of this property indicates that the PA processor defined by this CPU node does not support these facilities and instructions. - + “external-control” @@ -1009,72 +1047,72 @@ This property, if present, indicates that the PA processor defined by this CPU node implements the External Control Facility as described in the “Optional Facilities and Instructions” appendix of Book - II of + II of . The absence of his property indicates that the PA processor defined by this CPU node does not support the External Control Facility. - + “general-purpose” prop-encoded-array: <none> This property, if present, indicates that the PA processor defined - by this CPU node implements the floating point instructions - fsqrt, - fsqrts and + by this CPU node implements the floating point instructions + fsqrt, + fsqrts and stfiwx. The absence of this property indicates that the PA processor defined by this CPU node does not support the floating - point instructions - fsqrt, - fsqrts and + point instructions + fsqrt, + fsqrts and stfiwx. - + “reservation-granule-size” - Standard property, encoded as with - encode-int, + Standard property, encoded as with + encode-int, that represents the reservation granule size (i.e., the minimum size of lock variables) supported by this processor, in bytes. - + “graphics” prop-encoded-array: <none> This property, if present, indicates that the PA processor defined - by this CPU node implements floating point instructions + by this CPU node implements floating point instructions fres, frsqrte, and fsel. The absence of this property indicates that the PA processor defined by this CPU node does not support the floating - point instructions + point instructions fres, frsqrte, and fsel. - + “performance-monitor” property name: Indicates that the processor described by this node implements a performance monitor. prop-encoded-array: Consists of a pair of values, - each encoded as with - encode-int. + each encoded as with + encode-int. The first value of the pair shall be 0 indicating that the performance monitor functionality is implementation specific. The second value of the pair represents the documentation describing the performance monitor functionality implemented by the processor described by this node. The documentation represented by the - second value is specified in + second value is specified in . - + Documentation for Implementation Specific Performance Monitors @@ -1125,24 +1163,24 @@
- + “ibm,vmx” property name that indicates that the processor supports the POWER VMX architecture. - prop-encoded-array: an integer encoded as with - encode-int, + prop-encoded-array: an integer encoded as with + encode-int, that represents the level of the VMX architecture supported. The first level supported is the value 1. The - value of 1 represents the level of support described by the + value of 1 represents the level of support described by the A Vector/SIMD Multimedia eXtension to the PowerPC Architecture, Specification Revision 1.2.3, 7/18/97 specification. The value - of 2 represents the level of support provided by the VSX option of + of 2 represents the level of support provided by the VSX option of level 2.06. - + “ibm,segment-page-sizes” @@ -1153,8 +1191,8 @@ segment-page-size-descriptor: a segment-page-size-header followed by a pte-lp-descriptor. segment-page-size-header: Consists of three cells - (X,Y,Z) encoded as with - encode-int. + (X,Y,Z) encoded as with + encode-int. The first cell represents the base page size of the segment (the page size which determines the hash value used to locate the segment's page table entries) as 2 @@ -1168,8 +1206,8 @@ segment-page-size-header) pte-lp-encoding(s), one for each of the page sizes supported for this base segment page size. pte-lp-encoding: Each pte-lp-encoding consists of - two cells (P,Q) encoded as with - encode-int. + two cells (P,Q) encoded as with + encode-int. The first cell represents the page size of the encoding as 2 P (thus implying the number of low order RPN bits @@ -1177,22 +1215,22 @@ 12 bit positions, is the encoding to be entered into the available low order RPN bits to represent this page size for this segment base page size. - Note: A + Note: A segment-page-size-descriptor applies to a segment only if the size of the segment is greater than or equal to all of the - page sizes within the - pte-lp-encoding (s) contained within the + page sizes within the + pte-lp-encoding (s) contained within the segment-page-size-descriptor. - + “ibm,processor-page-sizes” property name: Relates the number and sizes of the virtual memory page sizes supported by the processor describe by this node. prop-encoded-array: One to N cells in ascending - value order, each encoded as with + value order, each encoded as with encode-int, each cell represents the size of a supported virtual memory page where the value of the cell is the power of 2 of the cell size. i.e. a 4 K page size is represented by the value 12 @@ -1200,20 +1238,20 @@ 12) etc. - + “ibm,processor-radix-AP-encodings” - property name: Relates the AP (Actual Page size) encodings - for the supported page sizes used by the TLB management instructions when the processor + property name: Relates the AP (Actual Page size) encodings + for the supported page sizes used by the TLB management instructions when the processor is in Radix address translation mode. - prop-encoded-array: One to N cells in ascending order of + prop-encoded-array: One to N cells in ascending order of Radix mode supported page size, each encoded as with - encode-int. The top 3 bits of the low order byte + encode-int. The top 3 bits of the low order byte contain the tlbie AP field associated with the corresponding Radix mode supported page size. - + “ibm,processor-segment-sizes” @@ -1221,7 +1259,7 @@ virtual memory segment sizes supported by the processor described by this node. prop-encoded-array: One to N cells in ascending - value order of the segment selector (SLBE B field), each encoded as with + value order of the segment selector (SLBE B field), each encoded as with encode-int, each positive value cell represents the size of a supported virtual memory segment where the value of the cell is the power of 2 of the segment size. That is, a 256Meg segment size is @@ -1230,14 +1268,14 @@ unsupported encodings). - + “ibm,processor-storage-keys” property name indicating the number of virtual storage keys supported by the processor described by this node. prop-encoded-array: Consists of two cells encoded as - with encode-int. + with encode-int. The first cell represents the number of virtual storage keys supported for data accesses while the second cell represents the number of virtual storage keys supported for instruction @@ -1245,78 +1283,78 @@ supported for the access type. - + “ibm,processor-vadd-size” property name indicating the number of virtual address bits that are supported by the processor described by this node. - prop-encode-array: An integer, encoded as with + prop-encode-array: An integer, encoded as with encode-int, that represents the number of supported virtual address bits. - Note: A processor + Note: A processor described by this node implements - the least significant - “ibm,processor-vadd-size” + the least significant + “ibm,processor-vadd-size” bits of the architected virtual address. - + “ibm,vrma-page-sizes” property-name: Maps the VRMASD field values implemented by the processor described by this node to their page sizes. - prop-encoded-array: Array of one or more + prop-encoded-array: Array of one or more VRMA page-size-descriptor (s) starting with the value selected by the firmware when booting the partition, followed by the other values supported by the platform. VRMA page-size-descriptor: A pair of cells encoded - as with + as with encode-int; The first cell is the log base 2 of the page size. The second cell contains, in its low order bits, the VRMASD field value to achieve that supported size. The high order bits of the second cell are zero. - + “ibm,estimate-precision” property name: Relates PA estimate instruction mnemonics to precisions supported by the processor described by this node. - prop-encoded-array: One or more + prop-encoded-array: One or more instruction-precision descriptor (s). - instruction-precision descriptor: An - instruction descriptor followed by a - precision descriptor. An + instruction-precision descriptor: An + instruction descriptor followed by a + precision descriptor. An instruction-precision descriptor relates one estimate instruction mnemonic to the precision supported by the processor described by this node for that estimate instruction mnemonic. instruction descriptor: Consists of one PA - instruction mnemonic encoded as with + instruction mnemonic encoded as with encode-string. precision descriptor: Consists of an integer, encoded - as with - encode-int, + as with + encode-int, specifying the number of bits of precision the processor described by this node supports for an instruction mnemonic. - + “ibm,dfp” property name: Indicates that the processor described by this node supports the Decimal Floating Point (DFP) architecture. - prop-encoded-value: an integer, encoded as with - encode-int, + prop-encoded-value: an integer, encoded as with + encode-int, that represents the level of DFP support of the CPU described by this node. The absolute value of the integer represents the level of the DFP architecture supported. The sign of the @@ -1324,69 +1362,69 @@ integer indicates native support while a negative integer indicates emulation assisted support. The absolute values supported are as follows: - 1: Represents the level of support defined by Version 2.05 of the + 1: Represents the level of support defined by Version 2.05 of the . - 2: Represents the level of support defined by Version 2.06 of the + 2: Represents the level of support defined by Version 2.06 of the . - + “ibm,purr” property name: Indicates that the processor described by this node implements a Processor Utilization of Resources Register (PURR). - prop-encoded-value: an integer, encoded as with - encode-int, + prop-encoded-value: an integer, encoded as with + encode-int, that represents the level of PURR architecture supported. The first level supported is the value 1 and is defined by Section 6.5 “Processor Utilization of Resources Register” of Book III of version 2.02 of the PA. - + “ibm,spurr” property name: Indicates that the processor described by this node implements a Scaled Processor Utilization of Resources Register (SPURR). - prop-encoded-value: an integer, encoded as with - encode-int, + prop-encoded-value: an integer, encoded as with + encode-int, that represents the level of SPURR architecture supported. The value of 1 represents the level of support - defined by Version 2.05 of the + defined by Version 2.05 of the . - + “ibm,pa-features” property name: Indicates level of support of several extended features of the Processor Architecture. - prop-encoded-array: One or more + prop-encoded-array: One or more attribute-descriptor (s). - attribute-descriptor: Consists of an - attribute-header immediately followed by an + attribute-descriptor: Consists of an + attribute-header immediately followed by an attribute-specifier. attribute-header: Consists of two bytes. The first byte is an unsigned integer representing a value from 1 to 254. The first - byte specifies the number of bytes implemented by the platform of the + byte specifies the number of bytes implemented by the platform of the attribute-specifier. The second byte is an unsigned - integer specifying the + integer specifying the attribute-specifier-type. - attribute-specifier: The - attribute-specifier is defined by the - attribute-specifier-type of the - attribute-header. The - attribute-specifier for the - attribute-specifier-type value of 0 is defined by + attribute-specifier: The + attribute-specifier is defined by the + attribute-specifier-type of the + attribute-header. The + attribute-specifier for the + attribute-specifier-type value of 0 is defined by . - + - Definition for + <title>Definition for <emphasis>attribute-specifier</emphasis> <emphasis>attribute-specifier-type</emphasis> value 0 @@ -1478,7 +1516,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1571,8 +1609,8 @@ instructions. - The value of 1 indicates support for the - frin, friz, frip, and + The value of 1 indicates support for the + frin, friz, frip, and frim instructions; else these instructions are not supported. @@ -1667,7 +1705,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1694,7 +1732,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1773,7 +1811,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1809,7 +1847,7 @@ Reserved for future storage order options - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1875,7 +1913,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1908,7 +1946,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1958,7 +1996,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -1992,7 +2030,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2025,7 +2063,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2059,7 +2097,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2074,7 +2112,7 @@ Undefined - Readers + Readers shall ignore undefined bytes if present. @@ -2084,34 +2122,34 @@
- + “ibm,pi-features” property name: Indicates level of support of processor implementation specific options not described by the Processor Architecture. - prop-encoded-array: One or more + prop-encoded-array: One or more pi-attribute-descriptor (s). - pi-attribute-descriptor: Consists of a - pi-attribute-header immediately followed by a + pi-attribute-descriptor: Consists of a + pi-attribute-header immediately followed by a pi-attribute-specifier. pi-attribute-header: Consists of two bytes. The first byte is an unsigned integer representing a value from 1 to 254. The first - byte specifies the number of bytes implemented by the platform of the + byte specifies the number of bytes implemented by the platform of the pi-attribute-specifier. The second byte is an - unsigned integer specifying the + unsigned integer specifying the pi-attribute-specifier-type. - pi-attribute-specifier: The - pi-attribute-specifier is defined by the - pi-attribute-specifier-type of the - pi-attribute-header. The - pi-attribute-specifier for the - pi-attribute-specifier-type value of 0 is defined by + pi-attribute-specifier: The + pi-attribute-specifier is defined by the + pi-attribute-specifier-type of the + pi-attribute-header. The + pi-attribute-specifier for the + pi-attribute-specifier-type value of 0 is defined by . - + - Definition for + <title>Definition for <emphasis>‘</emphasis> <emphasis>pi-attribute-specifier-type</emphasis> value 0 @@ -2173,7 +2211,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2185,7 +2223,7 @@ Ordered Thread Activation/Deactivation - The value of 1 indicates that the + The value of 1 indicates that the “ibm,ppc-interrupt-server-#s” property conveys the order that threads need to be activated and deactivated in to achieve optimal performance; else no need to @@ -2200,7 +2238,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2215,7 +2253,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2224,40 +2262,40 @@
- + “ibm,negotiated-pa-features” - property name: Indicates level - of support negotiated via the - ibm,client-architecture-support - method (See + property name: Indicates level + of support negotiated via the + ibm,client-architecture-support + method (See ) of several extended features of the Processor Architecture. - prop-encoded-array: One or more + prop-encoded-array: One or more negotiated-pa-attribute-descriptor (s). - negotiated-pa-attribute-descriptor: Consists of a + negotiated-pa-attribute-descriptor: Consists of a negotiated-pa-attribute-header immediately followed - by a + by a negotiated-pa-attribute-specifier. negotiated-pa-attribute-header: Consists of two bytes. The first byte is an unsigned integer representing a value from 1 to 254. The first byte specifies the number of bytes implemented by the - platform of the + platform of the negotiated-pa-attribute-specifier. The second byte - is an unsigned integer specifying the + is an unsigned integer specifying the negotiated-pa-attribute-specifier-type. - negotiated-pa-attribute-specifier: The - negotiated-pa-attribute-specifier is defined by the - negotiated-pa-attribute-specifier-type of the - negotiated-pa-attribute-header. The - negotiated-pa-attribute-specifier for the + negotiated-pa-attribute-specifier: The + negotiated-pa-attribute-specifier is defined by the + negotiated-pa-attribute-specifier-type of the + negotiated-pa-attribute-header. The + negotiated-pa-attribute-specifier for the negotiated-pa-attribute-specifier-type value of 0 is - defined by + defined by . - + - Definition for + <title>Definition for <emphasis>negotiated-pa-attribute-specifier</emphasis> <emphasis>negotiated-pa-attribute-specifier-type</emphasis> value 0 @@ -2316,7 +2354,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2331,7 +2369,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2340,37 +2378,37 @@
- + “ibm,raw-pi-features” property name: Indicates level of support of processor implementation specific options not described by the Processor - Architecture and not supported on partitions that contain the + Architecture and not supported on partitions that contain the “ibm,migratable-partition” property. - prop-encoded-array: One or more + prop-encoded-array: One or more raw-pi-attribute-descriptor (s). - raw-pi-attribute-descriptor: Consists of a - raw-pi-attribute-header immediately followed by a + raw-pi-attribute-descriptor: Consists of a + raw-pi-attribute-header immediately followed by a raw-pi-attribute-specifier. raw-pi-attribute-header: Consists of two bytes. The first byte is an unsigned integer representing a value from 1 to 254. The first byte specifies the number of bytes implemented by the platform of - the + the raw-pi-attribute-specifier. The second byte is an - unsigned integer specifying the + unsigned integer specifying the raw-pi-attribute-specifier-type. - raw-pi-attribute-specifier: The - raw-pi-attribute-specifier is defined by the - raw-pi-attribute-specifier-type of the - raw-pi-attribute-header. The - raw-pi-attribute-specifier for the + raw-pi-attribute-specifier: The + raw-pi-attribute-specifier is defined by the + raw-pi-attribute-specifier-type of the + raw-pi-attribute-header. The + raw-pi-attribute-specifier for the raw-pi-attribute-specifier-type value of 0 is defined - by + by . - + - Definition for + <title>Definition for <emphasis>raw-pi-attribute-specifier</emphasis> <emphasis>raw-pi-attribute-specifier-type</emphasis> value 0 @@ -2415,9 +2453,9 @@ The value of 1 indicates that the PA processor defined by - this CPU node implements the - mftgpr and - mffgpr instructions as described by IBM + this CPU node implements the + mftgpr and + mffgpr instructions as described by IBM POWER6® CEC Book IV Implementation Features; else not supported. @@ -2430,7 +2468,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2445,7 +2483,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2454,36 +2492,36 @@
- + “ibm,pa-optimizations” property name: Indicates the level of support of performance variabilities described by the Processor Architecture. - prop-encoded-array: One or more + prop-encoded-array: One or more pa-optimization-attribute-descriptor (s). - pa-optimization-attribute-descriptor: Consists of a + pa-optimization-attribute-descriptor: Consists of a pa-optimization-attribute-header immediately followed - by a + by a pa-optimization-attribute-specifier. pa-optimization-attribute-header: Consists of two bytes. The first byte is an unsigned integer representing a value from 1 to 254. The first byte specifies the number of bytes implemented by the - platform of the + platform of the pa-optimization-attribute-specifier. The second byte - is an unsigned integer specifying the + is an unsigned integer specifying the pa-optimization-attribute-specifier-type. - pa-optimization-attribute-specifier: The + pa-optimization-attribute-specifier: The pa-optimization-attribute-specifier is defined by the - pa-optimization-attribute-specifier-type of the - pa-optimization-attribute-header. The - pa-optimization-attribute-specifier for the + pa-optimization-attribute-specifier-type of the + pa-optimization-attribute-header. The + pa-optimization-attribute-specifier for the pa-optimization-attribute-specifier-type value of 0 - is defined by + is defined by . - + - Definition for + <title>Definition for <emphasis>pa-optimization-attribute-specifier</emphasis> <emphasis>pa-optimization-attribute-specifier-type</emphasis> value 0 @@ -2529,7 +2567,7 @@ The value is an unsigned quantity indicating the number - of data stream IDs supported. The value of this byte + of data stream IDs supported. The value of this byte shall be zero for processors that do not support data streams. @@ -2547,9 +2585,9 @@ The value in the Default Prefetch Depth (DPFD) field of the Logical Partitioning Control Register (LPCR) as described - by version 2.05 of PA. Unimplemented high order bits + by version 2.05 of PA. Unimplemented high order bits shall be zero. This byte is valid only if - the “2.05 Data Stream Support” bit of + the “2.05 Data Stream Support” bit of “ibm,pa-features” is set to one; else this byte is undefined. @@ -2565,7 +2603,7 @@ Reserved - Reserved bits within defined bytes + Reserved bits within defined bytes shall be zero. @@ -2575,14 +2613,14 @@ - + - +
TLB properties - + Since the PA defines the MMU as being part of the processor, the - properties defined by Section 3.6.5 of + properties defined by Section 3.6.5 of and the following MMU-related properties shall be presented under “cpu” nodes. @@ -2590,22 +2628,22 @@ “tlb-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the total number of TLB entries. - + “tlb-sets” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the number of associativity sets of the TLB. A value of 1 indicates that the TLB is fully-associative. - + “tlb-split” @@ -2614,71 +2652,71 @@ has a unified organization. - + “d-tlb-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the total number of d-TLB entries. - + “d-tlb-sets” - Standard property name, encoded as with - encode-int, that represents - the number of associativity sets of the d-TLB. A value of 1 indicates that the + Standard property name, encoded as with + encode-int, that represents + the number of associativity sets of the d-TLB. A value of 1 indicates that the d-TLB is fully-associative. - + “i-tlb-size” - Standard property name, encoded as with - encode-int, that + Standard property name, encoded as with + encode-int, that represents the total number of i-TLB entries. - + “i-tlb-sets” - Standard property name, encoded as with - encode-int, that represents - the number of associativity sets of the i-TLB. A value of 1 indicates that the + Standard property name, encoded as with + encode-int, that represents + the number of associativity sets of the i-TLB. A value of 1 indicates that the i-TLB is fully-associative. - + “tlbia” prop-encoded-array: <none> This property, if present, indicates that the PA processor defined - by this CPU node implements thetlbia instruction. The absence - of this property indicates that the PA processor defined by this CPU node does + by this CPU node implements thetlbia instruction. The absence + of this property indicates that the PA processor defined by this CPU node does not support the tlbia instruction. - +
- +
Internal (L1) cache properties - + The PA defines a Harvard-style cache architecture; however, unified caches are an implementation option. All of the PA cache instructions act upon a cache “block”. The coherence block size, if different - from the cache block size, is reported via the - “i-cache-line-size” and + from the cache block size, is reported via the + “i-cache-line-size” and “d-cache-line-size” properties. The internal (also referred to as “L1”) caches of PA processors are represented in the OF device tree by the following properties - contained under + contained under “cpu” nodes. @@ -2693,104 +2731,104 @@ so that data cache stores appear in the instruction cache. - + “i-cache-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the total size (in bytes) of the internal instruction cache. - + “i-cache-sets” - Standard property name, encoded as with - encode-int, that represents - number of associativity sets of the internal instruction cache. A value of 1 + Standard property name, encoded as with + encode-int, that represents + number of associativity sets of the internal instruction cache. A value of 1 signifies that the instruction cache is fully associative. - + “i-cache-block-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the internal instruction cache's block size, in bytes. - + “d-cache-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the total size (in bytes) of the internal data cache. - + “d-cache-sets” - Standard property name, encoded as with - encode-int, that represents - number of associativity sets of the internal data cache. A value of 1 signifies + Standard property name, encoded as with + encode-int, that represents + number of associativity sets of the internal data cache. A value of 1 signifies that the data cache is fully associative. - + “d-cache-block-size” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the internal (L1) data cache's block size, in bytes. - + “l2-cache” - Standard property name, encoded as with - encode-int, that represents + Standard property name, encoded as with + encode-int, that represents the next level of cache in the memory hierarchy. Absence of this property indicates that no further levels of cache - are present. If present, its value is the + are present. If present, its value is the phandle of the device node that represents the next level of cache. - + “i-cache-line-size” - Standard property name, encoded as with - encode-int, that represents - the internal instruction cache's coherency block size (line size), in bytes, + Standard property name, encoded as with + encode-int, that represents + the internal instruction cache's coherency block size (line size), in bytes, if different than its cache block size. - + “d-cache-line-size” - Standard property name, encoded as with - encode-int, that represents - the internal data cache's coherency block size (line size), in bytes, if different + Standard property name, encoded as with + encode-int, that represents + the internal data cache's coherency block size (line size), in bytes, if different than its cache block size. - Note: If this is a unified cache, the + Note: If this is a unified cache, the corresponding i- and d- sizes must be equal. - +
- +
Memory Management Unit properties - + To aid a client in “taking over” the translation mechanism and still interact with OF (via the client interface), the client needs to know what translations have been established by OF. The @@ -2804,21 +2842,21 @@ This property, consisting of sets of translations, defines the currently active translations that have been established by OF (e.g., using map). Each set has the following format: - - Each value is encoded as with + + Each value is encoded as with encode-int. - +
- +
SLB properties - + Since the PA defines the MMU as being part of the processor, the - properties defined by Section 3.6.5 of + properties defined by Section 3.6.5 of and the following MMU-related properties as appropriate to the specific processor implementation shall be presented under “cpu” nodes. @@ -2827,8 +2865,8 @@ “slb-size” - Standard property name, encoded as with - encode-int, that + Standard property name, encoded as with + encode-int, that represents the total number of SLB entries. Note: requires that the SLB be @@ -2838,17 +2876,17 @@ - +
- +
Ancillary (L2,L3...) cache node properties Some systems might include secondary (L2) or tertiary (L3), etc. cache(s). As with the L1 caches, they can be implemented as either Harvard-style or unified. Unlike the L1 properties, that are contained - within the + within the “cpu” nodes, the properties of ancillary caches are contained within other device tree nodes. The following properties define the characteristics of such @@ -2856,14 +2894,14 @@ of one of the CPU nodes or, for platforms that support dynamic reconfiguration of cpus, the CPUS node; this is to allow path-name access to the node. These properties shall always be contained within a child - node of the CPUS node. All + node of the CPUS node. All “cpu” nodes that share the same ancillary cache (including the cpu node under which the ancillary cache node is - contained) shall contain an - “l2-cache” property whose value is the + contained) shall contain an + “l2-cache” property whose value is the phandle of that ancillary cache node. - Note: The + Note: The “l2-cache” property shall be used in one level of the cache hierarchy to represent the next level. The device node for a subsequent level shall appear as a child of one of the caches in @@ -2876,7 +2914,7 @@ “device_type” Standard property name; the device_type of ancillary cache - nodes shall be + nodes shall be “cache”. @@ -2896,7 +2934,7 @@ “i-cache-size” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents the total size (in bytes) of the instruction cache at this node. @@ -2905,7 +2943,7 @@ “i-cache-sets” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents number of associativity sets of the instruction cache at this node. A value of 1 signifies that the instruction cache is fully associative. @@ -2915,7 +2953,7 @@ “d-cache-size” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents the total size (in bytes) of the data cache at this node. @@ -2924,7 +2962,7 @@ “d-cache-sets” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents number of associativity sets of the instruction cache at this node. A value of 1 signifies that the instruction cache is fully associative. @@ -2934,11 +2972,11 @@ “l2-cache” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents the next level of cache in the memory hierarchy. Absence of this property indicates that no further levels of cache - are present. If present, its value is the + are present. If present, its value is the phandle of the device node that represents the cache at the next level. @@ -2947,7 +2985,7 @@ “i-cache-line-size” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents the internal instruction cache's line size, in bytes, if different than its block size. @@ -2956,7 +2994,7 @@ “d-cache-line-size” - Standard property name, encoded as with + Standard property name, encoded as with encode-int, that represents the internal data cache's line size, in bytes, if different than its block size. @@ -2965,68 +3003,68 @@ - +
- + - +
Methods - + This section describes the additional standard methods required of a PA OF implementation. - +
MMU related methods - - The MMU methods defined by section 3.6.5. of + + The MMU methods defined by section 3.6.5. of shall be implemented by CPU - nodes. The value of the - mode parameter for the relevant methods (e.g., + nodes. The value of the + mode parameter for the relevant methods (e.g., map) shall be the value that is contained within PTEs that control Write-through, Cache-Inhibit, Memory-coherent, Guarded - and the 2 protection bits; thus, its format is: + and the 2 protection bits; thus, its format is: WIMGxPP, where x is a reserved bit that shall be 0. In order for I/O accesses to be properly performed in a LoPAR system, - address ranges that are mapped by + address ranges that are mapped by map-in shall be marked as Cache-Inhibited, Guarded. - The default mode (i.e., the mode specified when the value of the - mode argument is -1) for the - map-in and + The default mode (i.e., the mode specified when the value of the + mode argument is -1) for the + map-in and modify MMU methods of CPU nodes is defined as follows: If the beginning of the physical address range affected by the - operation refers to system memory, the values for + operation refers to system memory, the values for WIMGxPP shall be W=0, I=0, M=0, G=1, PP=10. If the beginning of the physical address range affected by the operation refers to an I/O address, the values for WIMGxPP shall be W=1, I=1, M=0, G=1, PP=10. - +
- +
- +
Client Interface Requirements - + A PA OF implementation shall implement a client interface (as defined - in chapter 6 of + in chapter 6 of ) according to the specifications contained within this section. - +
Calling Conventions - To invoke a client interface service, a - client program constructs a client interface + To invoke a client interface service, a + client program constructs a client interface argument array as specified in the core OF document, - places its address in - r3 and transfers to the + places its address in + r3 and transfers to the client interface handler, with the return address in lr. (A typical way of accomplishing this is to copy - the - client interface handler's address into - ctr and executing a + the + client interface handler's address into + ctr and executing a bctrl.) The term “preserved” below shall mean that the register has the same value when returning as it did when the call was @@ -3374,34 +3412,34 @@
Notes: - - + + Only the non-volatile fields ( cr2-cr4) need to be preserved. - As defined by section 6.3.1. of + As defined by section 6.3.1. of . Other special purpose registers - - - The + + + The client interface handler shall perform the service specified by the contents of the argument array that begins at the - address in + address in r3, place the return value (indicating success or - failure of the attempt to invoke the client interface service) back into - r3, and return to the + failure of the attempt to invoke the client interface service) back into + r3, and return to the client program. This is typically done by a Branch to Link Register ( blr). - The + The client interface handler shall preserve the contents of the Stack Pointer (r1), TOC Pointer (r2), Condition Register ( cr) all non-volatile registers (r13-r31) and all @@ -3410,53 +3448,53 @@ correctly. OF shall not depend upon whether its client is TOC-based or not. If the client interface handler, itself, is TOC-based, it must - provide for the appropriate initialization of its + provide for the appropriate initialization of its r2. - +
- + - +
Client Program Requirements - +
Load Address - - The client’s load address is specified by the value of the - load-base Configuration Variable. The value of - load-base defines the default load address for - client programs when using the - load method. + + The client’s load address is specified by the value of the + load-base Configuration Variable. The value of + load-base defines the default load address for + client programs when using the + load method. Load-base shall be a real address in real mode or a virtual address in virtual mode. Note that this address represents the - area into which the client program file will be read by + area into which the client program file will be read by load; it does not correspond to the addresses at - which the program will be executed. All of physical memory from + which the program will be executed. All of physical memory from load-base to either the start of OF physical memory or the end of physical memory, whichever comes first, shall be available for loading the client program. - +
- +
Initial Program State This section defines the “initial program state”, the execution environment that exists when the first machine instruction of a - + client program of the format specified above begins execution. Many aspects of the “initial program state” are - established by - init-program, which sets the - saved program state so that subsequent execution of - go will begin execution of the + established by + init-program, which sets the + saved program state so that subsequent execution of + go will begin execution of the client program with the specified environment. - +
Initial Register Values Upon entry to the client program, the following registers shall contain the following values: - + Initial Register Values @@ -3545,7 +3583,7 @@   - IP, see + IP, see @@ -3557,7 +3595,7 @@   - IR,DR, see + IR,DR, see @@ -3591,7 +3629,7 @@ r1 - See + See @@ -3636,7 +3674,7 @@ r5 - See + See @@ -3648,7 +3686,7 @@ r6, r7 - See + See @@ -3672,78 +3710,78 @@ Notes: - - + + OF will typically require the use of external interrupts for its - - user interface. However, when a + + user interface. However, when a client program is invoked, external interrupts shall - be disabled. If a + be disabled. If a client program causes the invocation of the user - interface, external interrupts + interface, external interrupts may be re-enabled. - + The 601 processor uses a different mechanism for controlling the endian-mode of the processor. On the 601, the LE bit is contained in the HID0 register; this bit controls the endian-mode of both program and privileged states. - + OF does not make any assumptions about whether a client program is TOC-based or not. It is the responsibility of the client program to - set + set r2 to its TOC, if necessary. - + As defined in the relevant section of the platform binding. - - + + - +
Initial Stack - + Client programs shall be invoked with a valid stack pointer ( r1) with at least 32 KB of memory available for stack growth. The stack pointer shall be 16-byte aligned, reserving sufficient room for a linkage area (32 bytes above the address in r1). If the system is executing in Real-Mode, the value in r1 is a real address; if in Virtual-Mode, the address in r1 is a mapped virtual address. - +
- +
Client Interface Handler Address - - When client programs are invoked, + + When client programs are invoked, r5 shall contain the address of the entry point of - the + the client interface handler. If the system is executing in Real-Mode, the value in r5 is a real address; if in Virtual-Mode, the address in r5 is a mapped virtual address. Note: This address points to the first instruction of - the + the client interface handler, not to a procedure descriptor. - +
- +
Client Program Arguments - - The calling program + + The calling program may pass to the client an array of bytes of arbitrary content; if this array is present, its address and length shall be passed - in registers - r6 and + in registers + r6 and r7, respectively. For programs booted directly by OF, the length of this array is zero. Secondary boot programs may use this argument array to pass information to the programs that they @@ -3761,25 +3799,25 @@ boot command line arguments, typically consisting of the name of a file to be loaded by a secondary boot program followed by flags selecting various secondary boot and OS options, are provided to - client programs via the - “bootargs” and - “bootpath” properties of the + client programs via the + “bootargs” and + “bootpath” properties of the /chosen node. - +
- +
Caching - + The caches of the processor shall be enabled when the client program is called. The I-cache shall be consistent with the D-cache for all memory areas occupied by the client program. Memory areas allocated on behalf of the client program shall be marked as cacheable. Accesses to “I/O” devices (especially, to devices across “bridges”) shall be made with the register access words - (e.g., + (e.g., %rl@). All processors in a SMP system shall have the same consistent view of all memory areas (for data references). No more than one processor shall have a modified copy of the same data area in @@ -3788,12 +3826,12 @@ Note: If firmware makes cacheable M=0 data references from different processors on a SMP system, it may have to perform additional cache management to meet this requirement. - +
- +
Interrupts - + OF requires that interrupts be “vectored” to its handlers when it is in control of the processor; this will occur when the User Interface is running. Client Interface calls are considered to @@ -3811,33 +3849,33 @@ entry point and replace that location with a branch to its entry point. When OF returns control, it shall restore the RAM location to its original contents. - +
- +
Client callbacks - + This section defines the callback mechanism that allows OF to access services exported to it by the client program. As described in - section 6.3.2 and the glossary entries for - callback and - $callback in + section 6.3.2 and the glossary entries for + callback and + $callback in , the callback mechanism - follows the same rules as those of Client interface calls. I.e., an + follows the same rules as those of Client interface calls. I.e., an argument array is constructed by OF and the address - of that array is passed (via + of that array is passed (via r3) to the client’s callback routine; the - address of the callback routine is supplied to OF by means of the + address of the callback routine is supplied to OF by means of the set-callback client call. If the system is running in Real-Mode, the address of the client callback routine shall be a real address; if it is running in Virtual-Mode, the client callback routine address shall be a mapped virtual address. - +
Real-Mode physical memory management assist callback - + Once the control of physical memory is transferred to the client program, OF which is running in real-mode shall use the callback service provided by the client program to allocate physical memory. Client @@ -3851,12 +3889,12 @@ IN: [address] min_addr, [address] max_addr, size, mode OUT: error, [address] real_addr - This routine allocates a contiguous physical memory of - size bytes within the address range between + This routine allocates a contiguous physical memory of + size bytes within the address range between min_addr and - max_addr. The + max_addr. The mode parameter contains the WIMGxPP bits as defined - in + in A non-zero error code shall be returned if the mapping cannot be performed. If error code is zero (i.e. allocation is succeeded) the routine returns the base address of the @@ -3864,19 +3902,19 @@ - +
- +
Virtual address translation assist callbacks - - As mentioned in + + As mentioned in , when OF is in Virtual-Mode, client programs that take over control of the system’s memory management must provide a set of callbacks that implement MMU functions. This section defines the input arguments and return values for these callbacks. The notation follows the style used in chapter 6 of the OF - specification + specification . @@ -3887,13 +3925,13 @@ OUT: throw-code, error This routine creates system-specific translation information; this will typically include the addition of PTEs to the HTAB. If the mapping - is successfully performed, a value of zero shall be placed in the + is successfully performed, a value of zero shall be placed in the error cell of the argument array; a non-zero error - code shall be returned in + code shall be returned in error if the mapping cannot be performed. - + unmap @@ -3903,7 +3941,7 @@ address range. - + translate @@ -3913,11 +3951,11 @@ real) to which the virtual address ( virt) is mapped. If the translation is successful, a PTE shall be placed into the HTAB for this translation, the number of - return cells shall be four with the resulting real address returned in - real and - error shall be set to + return cells shall be four with the resulting real address returned in + real and + error shall be set to false (0). If the translation is not successful, the - number of return cells shall be two and + number of return cells shall be two and error shall be set to a non-zero error code. This call shall be made when OF handles a DSI/ISI within the User interface. A successful result of the translate call indicates that OF @@ -3926,42 +3964,42 @@ - +
- + - +
User Interface Requirements - + An implementation of OF for the PA shall conform to the core - requirements as specified in + requirements as specified in and the following PA-specific extensions. - +
Machine Register Access - - The following + + The following user interface commands represent PA registers within - the + the saved program state. Executing the command returns the saved value of the corresponding register. The saved value may be set - by preceding the command with + by preceding the command with to; the actual registers are restored to the saved - values when + values when go is executed. - The following command displays the PA processor's + The following command displays the PA processor's saved program state. .registers - +
Branch Unit Registers - + %cr @@ -3969,36 +4007,36 @@ Access saved copy of Condition Register. - + %ctr Access saved copy of Count Register. - + %lr Access saved copy of Link Register. - + %msr Access saved copy of the low order 16 bits of SRR1 register. - + - %srr0 and + %srr0 and %srr1 Access saved copy of Save/Restore Registers. - + %pc @@ -4007,21 +4045,21 @@ - +
- +
Fixed-Point Registers - %r0 through + %r0 through %r31 Access saved copies of fixed-point registers. - + %xer @@ -4030,32 +4068,32 @@ - %sprg0 through + %sprg0 through %sprg3 Access saved copies of SPRG registers. - +
- +
Floating-Point Registers - + Unlike the other registers, the floating point unit registers are not normally saved, since they are not used by OF. The following access words, therefore, access the registers directly. - %f0 through + %f0 through %f31 Access floating point registers. - + %fpscr @@ -4067,14 +4105,14 @@
- +
- +
Configuration Variables - + In addition to the standard Configuration Variables defined by the - core OF document + core OF document , the following Configuration Variables shall be implemented for the PA: @@ -4082,8 +4120,8 @@ “little-endian?” - This boolean variable controls the endian-mode of OF. If - true (-1), the endian-mode is Little-Endian; if + This boolean variable controls the endian-mode of OF. If + true (-1), the endian-mode is Little-Endian; if false (0), the endian-mode is Big-Endian. The default value is implementation dependent. @@ -4092,8 +4130,8 @@ “real-mode?” - This boolean variable controls the address translation mode of OF. If - true (-1), the addressing mode is Real-Mode; if + This boolean variable controls the address translation mode of OF. If + true (-1), the addressing mode is Real-Mode; if false (0), the addressing mode is Virtual-Mode. The default value is implementation dependent. @@ -4134,8 +4172,8 @@ “load-base” - This integer variable defines the default load address for - client programs when using the + This integer variable defines the default load address for + client programs when using the load method. The default value is implementation dependent. @@ -4143,23 +4181,23 @@
- +
MP Extensions - + This section specifies the application of OF to PA multiprocessor (MP) systems. An OF implementation for an MP PA system shall implement the extensions described in this section as well as the requirements described in previous sections of this binding. - +
The Device Tree - + This section defines an additional property under the - /chosen node for a MP extension. Refer to + /chosen node for a MP extension. Refer to for more details about the device tree structure for a MP Configuration. - +
Additional Properties @@ -4170,21 +4208,21 @@ “cpu” property name, identifies the running CPU. - prop-encode-array: An integer, encoded as with + prop-encode-array: An integer, encoded as with encode-int, which contains the i-handle of the CPU node that is associated with the “running” CPU. - +
- +
- +
Initialization - + OF shall select one processor, using an algorithm of its choice, to be the “master” processor, which performs the role of the single processor on a uniprocessor system, either booting the client or @@ -4192,9 +4230,9 @@ into stopped state, a state in which the processor does not perform OF or client functions and does not interfere with the operation of the master processor. A processor in stopped state remains in that state unless and - until an executing client starts it using the + until an executing client starts it using the start-cpu client service defined below. - Client programs shall use the OF + Client programs shall use the OF start-cpu client interface service to start all processors before it reclaims the OF memory On machines in which a machine check on one processor is broadcast @@ -4204,7 +4242,7 @@ in the event of a machine check. depicts the relationship of the - Running, Stopped and Idle States to each other. The + Running, Stopped and Idle States to each other. The Client Interface Service calls are shown as how to move between the states. @@ -4221,15 +4259,15 @@ - + Note: OF's memory cannot be reclaimed by a client if a CPU is in the “stopped” or “idle” state. - +
- +
Client Interface Services - + The following client interface services are added for MP support on PA systems. These interfaces make the client program responsible for any Inter-CPU communication needed for these interfaces. The rationale for @@ -4242,18 +4280,18 @@ IN: nodeid, pc, arg OUT: none - This client interface service starts the CPU. The + This client interface service starts the CPU. The nodeid is the phandle of a node whose device_type is “cpu”. Start-cpu arranges for the CPU identified by phandle in nodeid to begin executing client code at the real - address given by the - pc input with an argument, + address given by the + pc input with an argument, arg, passed in register r3. When it begins execution, the started processor shall be in the endian mode of the client program, and in real (not translated) addressing mode. The contents of registers other than r3 are indeterminate. - A client should not call + A client should not call start-cpu for the processor on which it is running, effectively restarting with a new pc and abandoning the only client thread. A jump or branch instruction shall be used instead to achieve the @@ -4264,8 +4302,8 @@ means that client threads running on different CPUs must use mutual exclusion to prevent more than one processor from making client service requests at any one time. The exceptions are that a client thread may - invoke either the - stop-self or + invoke either the + stop-self or idle-self client services defined below at any time. Note: The results are undefined if the CPU identified @@ -4283,8 +4321,8 @@ OF places the processor on which the caller was running into the “stopped” state. The client program is not-resumable. Note: When an MP client program exits, one CPU - invokes the - exit client interface service, the others invoke the + invokes the + exit client interface service, the others invoke the stop-self service. @@ -4297,15 +4335,15 @@ OF places the CPU on which this service was invoked into an 'idle' state, saving the *current state* of the client program, so that the client program may be resumed. - A processor in idle state can be resumed using - resume-cpu service defined below or restarted using + A processor in idle state can be resumed using + resume-cpu service defined below or restarted using start-cpu. If the processor is resumed, it executes - a normal return to the client, as if its call to + a normal return to the client, as if its call to idle-self had just completed. Note: When a client program wants to enter the - firmware user interface, one CPU invokes the - enter client interface service, the others invoke the + firmware user interface, one CPU invokes the + enter client interface service, the others invoke the idle-self service. The rational is that the user interface may affect the machine state in any way that it desires, therefore the client shall not depend on it. @@ -4317,60 +4355,60 @@ IN: nodeid OUT: none - This client interface service is used to resume an *idled* CPU. The + This client interface service is used to resume an *idled* CPU. The nodeid is the phandle of a CPU node in idle state. resume-cpu arranges for that CPU to restore the - CPU’s state as saved by + CPU’s state as saved by idle-self and begin return to the client, completing the idle-self client service call that placed the CPU into idle state. The results are undefined if the CPU identified by *phandle* is not in an - *idle* state by a previous call to the + *idle* state by a previous call to the idle-self client interface service. Note: When the client program is resumed via the GO (or similar) user interface command, the client program is resumed on the - CPU which called the + CPU which called the enter service; the client program is responsible for - calling the + calling the resume-cpu service to resume other idled CPU's, if that is the desired client program behavior. - +
- +
Breakpoints - + If the breakpoint is taken by the firmware, without the client program's assistance, the other CPUs will continue to run in the client program. The client program may field the breakpoint 'trap' or 'vector' and idle the other CPUs before entering the PROM. The platform binding document has to specify how this is done to avoid loss of state at breakpoint time. - +
- +
Serialization - + The firmware is a single threaded program, from the client - program's point of view. Only the - idle-self, - stop-self, - enter and + program's point of view. Only the + idle-self, + stop-self, + enter and exit client interfaces may be invoked simultaneously - on different CPUs. Furthermore, only a single CPU may invoke the - enter or + on different CPUs. Furthermore, only a single CPU may invoke the + enter or exit client interface at any one time. The other CPUs - must use the - idle-self or + must use the + idle-self or stop-self client interface service. Note: The results are undefined if the client program invokes client interface services including breakpoint traps (other than - the + the enter/exit stop-self/idle-self case listed above) simultaneously on more than a single CPU. @@ -4381,9 +4419,9 @@ a client interface service to avoid rescheduling a thread of execution in the firmware on a different CPU if such a mechanism exists in the client program. - +
- +
- - + + diff --git a/DeviceTree/ch_devtree_system.xml b/LoPAR/app_papr_binding.xml similarity index 99% rename from DeviceTree/ch_devtree_system.xml rename to LoPAR/app_papr_binding.xml index 0ecc79a..16e9997 100644 --- a/DeviceTree/ch_devtree_system.xml +++ b/LoPAR/app_papr_binding.xml @@ -15,13 +15,57 @@ limitations under the License. --> - System Binding + This appendix specifies the application of OF to a PAPR System, including + requirements and practices to support unique hardware and firmware specific to the + platform implementation. The core requirements and practices specified by OF must + be augmented by system-specific requirements to form a complete specification for + the firmware implementation of a PAPR System. This appendix establishes such + additional requirements pertaining to the platform and the support required by OF. + +
+ Overview + + This appendix specifies the application of + IEEE Std 1275-1994 Standard for Boot (Initialization, + Configuration) Firmware, Core Practices and Requirements, + Core Errata, IEEE P1275.7 and appropriate OF Standards + for LoPAR computer systems, including practices for client program + interface and data formats. + +
+ General Requirements for OF + An OF implementation for an LoPAR platform shall implement the + core requirements as defined in + , core errata + , the PA Processor-specific + extensions described in + , other appropriate bindings + and/or recommended practices contained in the references (see + ), and the LoPAR Binding + specific extensions described in this appendix. + In addition, an OF implementation for an LoPAR platform shall + implement the + Device Interface, + Client Interface and + User Interface as defined in + . + Some LoPAR Binding property names exceed the OF Base specification + limit of 31 characters. LoPAR OF implementations shall support property + names of at least 47 characters. +
+ +
+ + +
LoPAR Boot Flow @@ -12197,4 +12241,4 @@ else
- + diff --git a/Virtualization/ch_platform_hcalls.xml b/LoPAR/app_platform_hcalls.xml similarity index 98% rename from Virtualization/ch_platform_hcalls.xml rename to LoPAR/app_platform_hcalls.xml index abf23c2..ec64ec6 100644 --- a/Virtualization/ch_platform_hcalls.xml +++ b/LoPAR/app_platform_hcalls.xml @@ -1,8 +1,8 @@ - Platform Dependent hcall()s - This chapter defines the set of hypervisor calls (hcall()s) that are + This appendix defines the set of hypervisor calls (hcall()s) that are platform dependent. The existence and/or implementation of the hcall() can vary between firmware releases and between hardware platforms.
@@ -53,7 +53,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - H_GetPerformanceCounterInfo / + H_GetPerformanceCounterInfo / @@ -92,48 +92,48 @@ hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */ Parameters: - + size – size of the getPerformanceCounterInfoParms - + getPerformanceCounterInfoParms – parameter list indicating - which performance counter information to retrieve. + which performance counter information to retrieve. - + Semantics: - + Validate the getPerformanceInfoParms is accessible, else H_Privilege. - + Validate the size and contents of getPerformanceCounterInfoParms, else H_Parameter. - + Validate information is available for the firmware level and platform, else H_Not_Available. - + Validate partition is permitted to retrieve performance information, else H_Authority. - + Copy requested performance counters into getPerformanceInfoParms and return H_Success. - +
Performance_Counter_Info_Parms struct @@ -170,7 +170,7 @@ hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */ INPUT - See + See @@ -252,7 +252,7 @@ hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */
- The possible values for Requested_Information are as shown in + The possible values for Requested_Information are as shown in . @@ -614,4 +614,4 @@ hcall ( const uint64 H_GetPerformanceCounterInfo /* Retrieve performance info */ - + diff --git a/Virtualization/ch_splpar.xml b/LoPAR/app_splar.xml similarity index 98% rename from Virtualization/ch_splpar.xml rename to LoPAR/app_splar.xml index 444aca8..55294bf 100644 --- a/Virtualization/ch_splpar.xml +++ b/LoPAR/app_splar.xml @@ -1,10 +1,10 @@ - SPLPAR Characteristics Definitions
SPLPAR Characteristics Definitions - This chapter defines the string that is returned by the + This appendix defines the string that is returned by the ibm,get-system-parameter RTAS call when the parameter token value of 20 (SPLPAR Characteristics) is specified on the ibm,get-system-parameter RTAS call as per . @@ -12,7 +12,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
SPLPAR Terms The LoPAR Shared Processor Logical Partition option (SPLPAR) defines - many terms as presented in + many terms as presented in .
@@ -248,7 +248,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Key Words And Values - Table + Table defines the key words and the associated legal values that will be returned in the ASCII NULL terminated string when the parameter token value of 20 (SPLPAR characteristics) is @@ -491,7 +491,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Notes: - + 0=Threads are not bound, 1=Threads are bound. @@ -529,7 +529,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 0=Dedicated Donate Mode is disabled, 1=Dedicated Donate Mode is enabled. - +
- + diff --git a/Virtualization/ch_virtual_nic.xml b/LoPAR/app_virtual_nic.xml similarity index 98% rename from Virtualization/ch_virtual_nic.xml rename to LoPAR/app_virtual_nic.xml index 86e0f65..a0a95fa 100644 --- a/Virtualization/ch_virtual_nic.xml +++ b/LoPAR/app_virtual_nic.xml @@ -1,11 +1,11 @@ - A Protocol for VNIC Communications
Introduction - The VNIC protocol defined in this chapter defines the protocol to be - used with VNIC virtual IOA, as defined in + The VNIC protocol defined in this appendix defines the protocol to be + used with VNIC virtual IOA, as defined in . VNIC provides a mechanism which minimizes the number of times data is copied within the memory of the physical system. The virtual I/O model described herein allows for either @@ -15,7 +15,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This protocol is designed to fulfill the following requirements: - + Fast, efficient transfer and reception of Ethernet frames @@ -60,7 +60,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Extensible protocol for future functional additions - +
@@ -79,11 +79,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Zero Copy DMA Models - Unlike the Interpartition Logical LAN option (See + Unlike the Interpartition Logical LAN option (See ), the VNIC protocol allows for the physical Ethernet adapter associated with the VNIC device to securely target memory pages associated with a VNIC adapter for virtual I/O - operations. LoPAR defines two modes of LRDMA (See + operations. LoPAR defines two modes of LRDMA (See ). The use of Redirected RDMA is completely invisible to the VNIC adapter, and has no impact on the VNIC protocol defined here. It is left @@ -97,21 +97,21 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Protocol Overview - The CRQ and Sub-CRQ facilities as defined in + The CRQ and Sub-CRQ facilities as defined in are used to send and receive VNIC commands to system firmware. The different VNIC command types are defined - in + in . Throughout this document, boolean values assume 0 to be false, 1 to be true. Unless otherwise specified, all lengths are expected to be given in terms of bytes. Any setting or capability changed or enabled after a successful H_REGISTER_CRQ will be cleared when H_FREE_CRQ is performed. - The format of a VNIC command is shown in + The format of a VNIC command is shown in . The Command Type field of the - VNIC command is defined in + VNIC command is defined in . The Return Code for a a VNIC - command is always at offset 12 in the response, as shown in + command is always at offset 12 in the response, as shown in . All VNIC commands have VNIC command values from 0x0 to 0x7F. Each response to a VNIC command has a VNIC command value that is equal to the @@ -239,7 +239,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 1 - This field contains a value from + This field contains a value from that contains the high level return code for the operation. @@ -1515,7 +1515,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This section gives an overview of the typical VNIC startup sequence. - + The operating system discovers a VNIC device in the device tree. @@ -1534,13 +1534,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> VNIC client calls H_REG_CRQ specifying the unit address and IOBA of the CRQ page(s), and waits for either H_Success or an INITIALIZATION - message as defined in + message as defined in . VNIC client sends either an INITIALIZATION_COMPLETE or an - INITIALIZATION message to firmware using H_SEND_CRQ, as defined in + INITIALIZATION message to firmware using H_SEND_CRQ, as defined in . @@ -1624,7 +1624,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The firmware will send a LOGICAL_LINK_STATE_RSP once the link state is up. - +
@@ -1633,7 +1633,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> update the firmware on the adapter, or needs to remove the virtualized adapter from the partition, the following flows will happen. - + Firmware will close its CRQ and Sub-CRQs. @@ -1664,7 +1664,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> VNIC client opens the CRQ, and attempts the boot sequence. - +
@@ -1672,10 +1672,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> In the event that an active partition is migrated to a new platform, the following sequence takes place. - + VNIC client receives a TRANSPORT_EVENT event specifying Partner - Partition Suspended (Defined in + Partition Suspended (Defined in ). @@ -1703,20 +1703,20 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> VNIC client attempts the boot sequence. - +
Dump Typical dump collection flow: - + VNIC client decides on the need for a VNIC dump. - VNIC client sends a REQUEST_DUMP_SIZE command (see + VNIC client sends a REQUEST_DUMP_SIZE command (see ) to system firmware. @@ -1732,7 +1732,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - VNIC client sends a REQUEST_DUMP command (see + VNIC client sends a REQUEST_DUMP command (see ) to system firmware containing the IOBAs referring to the dump buffer. @@ -1749,11 +1749,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - System firmware sends a REQUEST_DUMP_RSP (see + System firmware sends a REQUEST_DUMP_RSP (see ) to the VNIC client, indicating the dump is complete. - +
@@ -1774,7 +1774,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Sub-CRQs may be presented to either the VNIC or system firmware with a single virtual interrupt. - + Operating system chooses a VNIC adapter to use for frame transmission. @@ -1788,7 +1788,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> VNIC client device driver constructs a Transmit Descriptor (or - multiples) describing the TCE mapped buffer (see + multiples) describing the TCE mapped buffer (see ). @@ -1810,7 +1810,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The physical Ethernet device driver interrupts system firmware (or system firmware polls for completion at appropriate times) indicating the frame has been successfully transmitted. System firmware constructs a - Transmit Completion Sub-CRQ event (see + Transmit Completion Sub-CRQ event (see ), and places that Sub-CRQ onto the Transmit Completion Sub-CRQ. @@ -1819,7 +1819,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> VNIC client removes the TCE mapping for the frame, and makes it available to its network stack. - +
@@ -1838,7 +1838,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> as efficient as possible. Multiple Sub-CRQs may be presented to either the VNIC or system firmware with a single virtual interrupt. - + When the VNIC client is started, the VNIC allocates several memory buffers to be used to the reception of Ethernet frames. The VNIC @@ -1848,7 +1848,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> For each receive buffer, the VNIC client creates Add Receive - Buffer Descriptor events (see + Buffer Descriptor events (see ), and gives them to system firmware via the Receive Buffer Add Sub-CRQ using H_SEND_SUB_CRQ or H_SEND_SUB_CRQ_INDIRECT. Once this is done, the VNIC client should not @@ -1872,7 +1872,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> System firmware receives an interrupt from the physical adapter saying a frame has arrived, and uses the information it saves to generate - a Receive Completion event Sub-CRQ (see + a Receive Completion event Sub-CRQ (see ), and places it on the appropriate Receive Completion Sub-CRQ. @@ -1881,7 +1881,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The VNIC client receives a virtual interrupt for its Receive Completion Sub-CRQ, and passes the frame up its network stack. - +
@@ -1889,7 +1889,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> All VNIC commands are sent using H_SEND_CRQ.
Version Exchange - The VERSION_EXCHANGE command as defined in + The VERSION_EXCHANGE command as defined in allow the VNIC protocol to be easily updated in the future. Each side is required to support the highest common version of the VNIC protocol specification, as exchanged @@ -1972,7 +1972,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Maximum version that VNIC client supports on a VERSION_EXCHANGE and the maximum version that system firmware supports on a VERSION_EXCHANGE_RSP. Each side must support the - highest common version between the two versions. A value from + highest common version between the two versions. A value from will be contained in this field. @@ -2002,7 +2002,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -2053,7 +2053,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
VNIC Capabilities - The VNIC capabilities command as defined in + The VNIC capabilities command as defined in is used to create an abstracted architecture for discovering and utilizing different NIC advanced functions on adapters, in an adapter-independent manner. As new @@ -2149,7 +2149,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 2 - This value should be one of the values from + This value should be one of the values from . @@ -2181,7 +2181,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -2400,7 +2400,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - Query only- Boolean value returned in Number. If TRUE, TCP/IP - offload commands defined in + offload commands defined in are supported. @@ -2563,11 +2563,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Login Support - The use of the LOGIN and LOGIN_RSP commands is defined in + The use of the LOGIN and LOGIN_RSP commands is defined in . The format of the LOGIN - command is defined in + command is defined in , and the LOGIN_RSP command is - defined in + defined in . There must be exactly one Transmit Submission Sub-CRQ for each Transmit Completion Sub-CRQ, and vice versa. Each is implicitly tied to @@ -2663,7 +2663,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field is an I/O bus address referring to a - TCE-mapped buffer containing the LOGIN Buffer as defined in + TCE-mapped buffer containing the LOGIN Buffer as defined in . @@ -3044,7 +3044,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field contains the number of supported Transmit - Descriptors, as detailed in + Descriptors, as detailed in . @@ -3221,7 +3221,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -3249,7 +3249,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> physical port configuration authority, the VNIC client may also use the SET_PHYS_PARMS command to change those values. The SET_PHYS_PARMS, QUERY_PHYS_PARMS, and QUERY_PHYS_CAPABILITIES - commands all use a common command format defined in + commands all use a common command format defined in . @@ -3415,7 +3415,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> On a response, this is a return code for the operation as - defined in + defined in . @@ -3429,7 +3429,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> parameters, the LOGICAL_LINK_STATE command and response provide a method for the VNIC to inform system firmware when it’s ready to receive packets. The format of the LOGICAL_LINK_STATE and LOGICAL_LINK_STATE_RSP - commands is defined in + commands is defined in . The current VNIC logical link state will always be returned in the Link State field on a LOGICAL_LINK_STATE_RSP. @@ -3547,7 +3547,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -3557,12 +3557,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
TCP, UDP, and IP Offload Support - The QUERY_IP_OFFLOAD command as defined in + The QUERY_IP_OFFLOAD command as defined in allows the VNIC client to determine what facilities exist in the VNIC system firmware, and its limitations, if any. Based on the capabilities and limitations, the CONTROL_IP_OFFLOAD - command as defined in + command as defined in allows the VNIC client to enable appropriate offload capabilities. QUERY_IP_OFFLOAD and CONTROL_IP_OFFLOAD must be done prior to successful LOGIN @@ -3676,7 +3676,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to return IP offload information. On reception of a successful QUERY_IP_OFFLOAD_RSP, - the buffer will be filled in with the structure as defined in + the buffer will be filled in with the structure as defined in . @@ -3691,7 +3691,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -3791,7 +3791,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field is an I/O bus address referring to a TCE-mapped buffer containing the parameters to enable or disable TCP, UDP, and IP offload. The format of this buffer is - defined in + defined in . @@ -3821,7 +3821,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -4486,9 +4486,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> the services in the manner it expects, it may utilize the dump support to collect focused debugging data collected and stored in VNIC client storage that’s been TCE-mapped. - The format of the REQUEST_DUMP command is defined in + The format of the REQUEST_DUMP command is defined in , and the format of the - REQUEST_DUMP_RSP command is defined in + REQUEST_DUMP_RSP command is defined in .
@@ -4596,7 +4596,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -4831,7 +4831,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -4863,11 +4863,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> require decreasing the size of a different component’s trace buffer.The REQUEST_RAS_COMP_NUM and REQUEST_RAS_COMP_NUM_RSP commands are - defined in + defined in , and the REQUEST_RAS_COMPS and - REQUEST_RAS_COMPS_RSP command format is defined in + REQUEST_RAS_COMPS_RSP command format is defined in . The COLLECT_FW_TRACE and - COLLECT_FW_TRACE_RSP commands are defined in + COLLECT_FW_TRACE_RSP commands are defined in .
@@ -4990,7 +4990,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> On a response, this field will contain a return code for - the request as defined in + the request as defined in . This field is reserved for a request. @@ -5090,7 +5090,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field contains an I/O bus address of a TCE-mapped buffer containing an array of Firmware Component structures as - defined in + defined in . The VNIC client should ensure the buffer is large enough to contain the number of components as returned in a REQUEST_RAS_COMP_NUM_RSP @@ -5124,7 +5124,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -5206,7 +5206,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field contains a Correlator for a Firmware Component - as defined in + as defined in that this command should act on. @@ -5300,7 +5300,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -5384,7 +5384,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field contains a Correlator for a Firmware Component - as defined in + as defined in that this command should act on. @@ -5434,7 +5434,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> used to collect the trace information. On a COLLECT_FW_RSP, this value will indicate how much trace data is actually placed in the buffer. The trace data is an array of entries with the - format as defined in + format as defined in . @@ -5449,7 +5449,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -5687,7 +5687,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 1 - This field shows the current trace level, as defined in + This field shows the current trace level, as defined in . A value of 0xFF indicates this component does not support tracing. @@ -5778,16 +5778,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Statistics Support - The REQUEST_STATISTICS command as defined in + The REQUEST_STATISTICS command as defined in is used by the VNIC client to obtain statistic counters kept by system firmware and the physical adapter supporting the VNIC. - The REQUEST_STATISTICS_RSP command is defined in + The REQUEST_STATISTICS_RSP command is defined in . In the event a given VNIC does not support the retrieval of certain of the statistics, the statistic will have a -1 value returned in it. - The REQUEST_DEBUG_STATS command defined in + The REQUEST_DEBUG_STATS command defined in is used by the VNIC client to retrieve an unarchitected block of statistics that is implementation dependent which may be used to debug firmware problems. This is an @@ -5904,7 +5904,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the VNIC - statistics block as defined in + statistics block as defined in . @@ -6042,7 +6042,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -6520,7 +6520,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -6532,14 +6532,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Error Reporting Support If system firmware encounters an error processing requests related to the physical adapter being virtualized by the VNIC interface, it will - generate ERROR_INDICATION commands to the VNIC client, as defined in + generate ERROR_INDICATION commands to the VNIC client, as defined in . The VNIC client may then, at its discretion, obtain detailed error information using the - REQUEST_ERROR_INFO command as defined in + REQUEST_ERROR_INFO command as defined in . It is the intent that the VNIC client should log the detailed error information using its normal error logging infrastructure and methods. - The REQUEST_ERROR_INFO_RSP command as defined in + The REQUEST_ERROR_INFO_RSP command as defined in is used by firmware to indicate the successful retrieval of error information. The retrieval of detailed error information allows firmware to reuse the resources for tracking @@ -6701,7 +6701,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 2 - This field contains a value as detailed in + This field contains a value as detailed in showing the cause of the error. @@ -6971,7 +6971,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -7070,7 +7070,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Link State Change - This LINK_STATE_INDICATION command as defined in + This LINK_STATE_INDICATION command as defined in is an unacknowledged command sent by system firmware to inform the VNIC client when the state of the link changes. The VNIC client can also use QUERY_PHYS_PARMS at any time @@ -7204,7 +7204,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Change MAC Address - The CHANGE_MAC_ADDR command defined in + The CHANGE_MAC_ADDR command defined in allows the VNIC client to change the current MAC address. The request to change may fail due to Access Control List entries set up by the administrator. @@ -7313,7 +7313,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -7323,7 +7323,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Multicast Support - The MULTICAST_CTRL command defined in + The MULTICAST_CTRL command defined in allows the VNIC client to manage the reception of Multicast Ethernet traffic. Individual multicast MAC addresses may be enabled and disabled, as well as all multicast @@ -7335,7 +7335,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> hardware supports it, or will enable all multicast addresses. When this is done, system firmware will report exact matches through the unique multicast Ethernet filter via the Exact Match bit defined in the Receive - Completion Descriptor as defined in + Completion Descriptor as defined in . If the Exact Match bit is off, and a multicast packet was returned in the Receive Completion Descriptor, the multicast packet either matches a non-exact hashing @@ -7470,7 +7470,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -7485,10 +7485,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> exact adapter may change during partition mobility operations, it is suggested this data not be relied upon operationally, and be used with the understanding that it may change from request to request. - The VPD commands are defined in - , - , - , and + The VPD commands are defined in + , + , + , and .
@@ -7672,7 +7672,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -7891,7 +7891,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -7903,13 +7903,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Access Control SupportThe VNIC may have certain Access Control Lists (ACLs) in effect, and some of these may change dynamically. The ACL_CHANGE_INDICATION - command defined in + command defined in is sent by system firmware to the VNIC client in the event any of the ACLs have changed dynamically. - The ACL_QUERY command defined in + The ACL_QUERY command defined in and its associated response - defined in + defined in may be used by the VNIC client to obtain information about the ACLs in effect to enable earlier error checking or ease of use functions. @@ -8103,7 +8103,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> TCE-mapped buffer used by system firmware to place the ACL information. Upon reception of a ACL_QUERY_RSP with a Success return code, this buffer will be filled in with the structure - as defined in + as defined in @@ -8227,7 +8227,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -8451,14 +8451,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Debugging Support - The TUNE command defined in + The TUNE command defined in may be used by the VNIC client to opaquely pass tuning data from the VNIC client to system firmware. As the exact firmware backing a VNIC client may change during partition mobility operations, it is suggested this data not be relied upon operationally, and be used with the understanding that it may change from adapter to adapter. - A TUNE_RSP command defined in + A TUNE_RSP command defined in will be generated by system firmware upon completion of the TUNE command. This command is an optional VNIC command, and may not be supported @@ -8675,7 +8675,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 4 - This is a return code for the operation as defined in + This is a return code for the operation as defined in . @@ -8700,13 +8700,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> returned in the LOGIN response specifying all versions of transmit descriptor supported by the VNIC. The versions of the transmit descriptor offering the best performance appear in the array first. All VNIC - versions will support Transmit Descriptor Version Zero defined in + versions will support Transmit Descriptor Version Zero defined in , but that version may not offer the best performance. - Transmit Descriptor Version Two defined in + Transmit Descriptor Version Two defined in is designed to be used in combination with a previous use of Transmit Descriptor Version Zero or - Transmit Descriptor Version One defined in + Transmit Descriptor Version One defined in
@@ -9058,7 +9058,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This is an array of 5 two byte integer return codes as - defined in + defined in . @@ -9582,7 +9582,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> In the event multiple Sub-CRQs are allocated for this purpose, it is the VNIC client’s responsibility to always allocate the receive buffer size for the Receive Buffer Add Sub-CRQs that are returned by system - firmware as defined in + firmware as defined in . System firmware will configure the correct buffer sizes based on the current VNIC maximum transmission unit, current number of Receive @@ -9887,4 +9887,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - + diff --git a/Virtualization/ch_virtual_scsi.xml b/LoPAR/app_virtual_scsi.xml similarity index 99% rename from Virtualization/ch_virtual_scsi.xml rename to LoPAR/app_virtual_scsi.xml index e43fc7b..41d8fac 100644 --- a/Virtualization/ch_virtual_scsi.xml +++ b/LoPAR/app_virtual_scsi.xml @@ -1,10 +1,10 @@ - A Protocol for VSCSI Communications
Introduction - The purpose of this chapter is to define the protocol used by + The purpose of this appendix is to define the protocol used by virtual SCSI (vscsi) client drivers and vscsi server drivers in sufficient detail to ensure compatibility between unlike operating systems implementing these features. The SCSI Architecture Model (SAM-2) defines @@ -258,25 +258,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo communication are required to perform virtual SCSI functions. These communications are made up of three classes of messages: - + Messages contained entirely within a single CRQ message - + SRP requests and responses, as defined by the SRP standard - + Management Datagrams - +
CRQ Message formats CRQ messages are 16 bytes (128 bits) in length. Only the first byte is architected by the Reliable Command/Response Transport specification - described earlier in this document. That specification is repeated in + described earlier in this document. That specification is repeated in .
@@ -345,7 +345,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo If the first byte of a CRQ message is 0x80, then it is a valid Command/Response entry and the second byte describes the format of message. Possible values for the second byte of the CRQ message when the first byte - is 0x80 are shown in + is 0x80 are shown in .
@@ -434,9 +434,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
If the format byte is 0x01, then the rest of the message is a vscsi SRP request or response message. The rest of the CRQ contents for this type - of message is shown in + of message is shown in , for messages from the clients, - and + and , for messages from the VIOS. Messages with a format byte of 0x02 are Management Datagram messages, defined later in this chapter. Messages formats of 0x03, 0x04, and 0x05 @@ -446,7 +446,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
CRQ VSCSI Client Message Format - Client messages are sent from the client partitions to the VIOS. + Client messages are sent from the client partitions to the VIOS. shows the format of these messages, @@ -549,7 +549,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
CRQ VSCSI VIOS Message Format VIOS messages are sent from the VIOS to the clients, usually in - response to a request from the client. The VIOS message format is shown + response to a request from the client. The VIOS message format is shown . @@ -735,7 +735,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo The inter_op structure is used to specify the type of MAD being sent. - - + MAD_NOT_SUPPORTED is returned if the VIOS is down-level. MAD_FAILED is returned in every other situation where the MAD did not succeed.The length field is set to the length of the data structure(s) used @@ -808,7 +808,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo The MAD_ERROR_LOGGING_REQUEST uses the following data structure: - @@ -875,7 +875,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo The MAD_ADAPTER_INFO_REQUEST uses the following data structure: - @@ -1195,4 +1195,4 @@ unsigned int cap_type; - + diff --git a/Virtualization/ch_virtual_tpm.xml b/LoPAR/app_virtual_tpm.xml similarity index 99% rename from Virtualization/ch_virtual_tpm.xml rename to LoPAR/app_virtual_tpm.xml index 4a7b822..821d922 100644 --- a/Virtualization/ch_virtual_tpm.xml +++ b/LoPAR/app_virtual_tpm.xml @@ -15,13 +15,13 @@ limitations under the License. --> - Virtual Trusted Platform Module (VTPM)
A protocol for VTPM communications - The protocol defined in this section is to be used with the VTPM as defined in + The protocol defined in this appendix is to be used with the VTPM as defined in . The VTPM provides the services of a TPM device to an associated client partition, the primary use of a VTPM is to enable software in the partition to perform a @@ -2369,4 +2369,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="ch_v
- + diff --git a/Virtualization/ch_virtual_tty.xml b/LoPAR/app_virtual_tty.xml similarity index 98% rename from Virtualization/ch_virtual_tty.xml rename to LoPAR/app_virtual_tty.xml index 0e4c67e..f47a7c1 100644 --- a/Virtualization/ch_virtual_tty.xml +++ b/LoPAR/app_virtual_tty.xml @@ -1,15 +1,15 @@ - A Protocol for a Virtual TTY Interface
Overview - This chapter defines a protocol to support partition use of a + This appendix defines a protocol to support partition use of a physical serial port using a virtual TTY (VTY) interface. A protocol is required to send control and status information of the physical device using a data only transport. Specifically, this protocol is used to allow the Virtual Terminal - (VTERM) option, as defined in + (VTERM) option, as defined in , as the interface to communicate with a physical serial port which is under control of the platform instead of the OS. @@ -45,11 +45,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
Data Packet - + This packet type is used to send data. - The data packet is defined in + The data packet is defined in .
@@ -137,7 +137,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo This packet type is used to send commands that control the operation of software or hardware on the other side of the link, and to send notification of status changes on the other side. - The control packet is defined in + The control packet is defined in .
@@ -237,7 +237,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition to the platform. Data Member Definition: The data member for this verb - consists of 8 bytes, as defined in + consists of 8 bytes, as defined in .
@@ -302,7 +302,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo be serialized with data packets.In the data portion of the packet, the first word defines the bit values to be set; the second word is a mask defining which bits are to be - updated. See + updated. See .
@@ -392,7 +392,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to the partition. Data Member Definition: The data member for this verb - consists of 4 bytes, as defined in + consists of 4 bytes, as defined in
@@ -439,9 +439,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo This packet is sent by platform to the partition to inform the partition of a change in status of certain bits in the VS_MODEM_CTL word. The bits which cause this command to be sent when they transition are - defined in + defined in . This command should be - serialized with data packets. The protocol version in + serialized with data packets. The protocol version in defines the first (lowest) version of the protocol in which a transition of this bit should cause the command to be sent. @@ -524,7 +524,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo below. There is in some case implied control of the state of the other side of the link, as a series of queries and responses are used to initialize (or re-initialize) the protocol. - The query packet is defined in + The query packet is defined in .
@@ -635,7 +635,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo This packet is used to reply to query packets sent from the other side of the link, and are sent only in response to query packets. - The query response packet is defined in + The query response packet is defined in .
@@ -799,7 +799,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
Packet Type and Verb Summary - A summary of packet types and verbs can be found in + A summary of packet types and verbs can be found in .
@@ -993,40 +993,40 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo discarded.The connection process is initiated by the partition side. The sequence is as follows: - + Both sides are in closed state. Both side are “listening” to the VTY. - + The partition sends the VSV_SEND_VERSION_NUMBER query. - + The partition continues listening, but discard any packet that is not a VSV_SEND_VERSION_NUMBER query response. - + The platform replies with the VSV_SEND_VERSION_NUMBER query response packet. - + The platform clears any pending data in the serial port hardware. - + The platform sends the VSV_SEND_VERSION_NUMBER query packet. - + The partition responds with the VSV_SEND_VERSION_NUMBER query response packet. - + At this point the protocol is open; any data received in the serial hardware by the platform from this point should be put into data packets and sent to the partition; any data packets received from the partition @@ -1038,4 +1038,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo device tree node to communicate an appropriate time-out value. - + diff --git a/Virtualization/ch_vmc_comm.xml b/LoPAR/app_vmc_comm.xml similarity index 99% rename from Virtualization/ch_vmc_comm.xml rename to LoPAR/app_vmc_comm.xml index 36cb6d5..3fd8aa0 100644 --- a/Virtualization/ch_vmc_comm.xml +++ b/LoPAR/app_vmc_comm.xml @@ -1,4 +1,4 @@ - A Protocol for VMC Communications @@ -38,13 +38,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> when the system is not HMC managed. This communication device borrows aspects from both VSCSI and ILLAN devices and is implemented using the CRQ and the RDMA interfaces. The - initialization process for CRQs is defined in + initialization process for CRQs is defined in , and is not duplicated here. A three way handshake is defined that must take place to establish that both the hypervisor and management partition sides of the channel are running prior to sending/receiving any of the protocol messages defined in this chapter. - Transport Event CRQs are also defined in + Transport Event CRQs are also defined in , and are not duplicated here. They define the CRQ messages that are sent when the hypervisor detects one of the peer partitions has abnormally terminated, or one side has @@ -194,7 +194,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> exchange of capabilities has completed are dropped. This message enables the management partition and the hypervisor to trade the following interface parameters: - + # HMC’s. Maximum number of independent HMC connections supported. Multiple connections would be required to support HMC pass @@ -221,9 +221,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> the hypervisor with the high-order byte indicating a major version and the low-order byte indicating a minor version. - + - +
VMC Capabilities Response @@ -241,7 +241,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- + 1 B @@ -323,7 +323,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> and the hypervisor. Many of the HMC Interface messages defined in following sections indicate buffers that contain data that must be transferred. Note the following: - + All buffers exist in the hypervisor memory, and data is moved between the hypervisor and the management partition by the management @@ -377,16 +377,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> There is a separate buffer pool for each LPM connection, each with the negotiated number of buffers. - + - +
HMC Interface Messages There are several different HMC Interface messages, as defined in the following sections. Each CRQ message has a unique HMC Interface message type, and the HMC Interface message type defines the format for the remaining 14 bytes of data. - +
Interface Open @@ -795,7 +795,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> and to 1 if the buffer being added is to be used for messages outbound from the hypervisor. The typical flow for adding buffers: - + A new LPM connection is opened by the management partition. @@ -817,7 +817,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> application that it has buffers available for sending HMC commands. - +
Add Buffer Response @@ -980,7 +980,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The hypervisor is expected to manage buffer usage with the LPM application directly and inform the management partition when buffers may be removed. The typical flow for removing buffers: - + The LPM application no longer needs a communication path to a particular hypervisor function. That function is closed. @@ -1006,7 +1006,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The management partition verifies it can remove the buffer. This is possible if buffers have been quiesced. - +
Remove Buffer Response @@ -1298,4 +1298,4 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- + diff --git a/LoPAR/bk_main.xml b/LoPAR/bk_main.xml new file mode 100644 index 0000000..e8791f7 --- /dev/null +++ b/LoPAR/bk_main.xml @@ -0,0 +1,386 @@ + + + + + + + Linux on Power Architecture Reference + A PAPR Linux Subset + + + + + System Software Work Group + + syssw-chair@openpowerfoundation.org + + OpenPOWER Foundation + + + + 2016, 2018, 2020 + OpenPOWER Foundation + + + Revision 0.5_pre6 + OpenPOWER + + + + + + Copyright details are filled in by the template. + + + + + + The purpose of this document is to provide firmware and software + architectural details associated with an OpenPOWER Systems. + The base content for this document were contributed to the OpenPOWER Foundation in the + IBM Linux on Power Architecture Platform Reference (LoPAPR) Draft + document which detailed Linux running on PowerVM. While this information is not always + immediately applicable to new OpenPOWER modes of bare metal or KVM, many of the + concepts and interfaces remain in some form. Until such time as the document addresses + these new OpenPOWER modes and components, it will remain versioned less than 1.0. It should + also be noted that the original document had numerous contributors inside IBM. + + This document is a Standard Track, Work Group Specification work product owned by the + System Software Workgroup and handled in compliance with the requirements outlined in the + OpenPOWER Foundation Work Group (WG) Process document. It was + created using the Master Template Guide version 0.9.5. Comments, + questions, etc. can be submitted to the public mailing list for this document at + syssw-linux_architecture_ref@mailinglist.openpowerfoundation.org. + + + + + + 2020-04-20 + + + + Revision 0.5_pre6 - Re-merge 5 sub-docs back into one matching PAPR. No technical updates. + + + + + + 2020-04-06 + + + + Revision 0.5_pre5 - Updates to include latest PAPR ACRs (2.9) as follows: + + + Add H_VIOCTL subfunctions for VNIC failover support + + + Add H_VIOCTL subfunction for virtual ethernet MAC scan functionality + + + Add H_VIOCTL subfunctions for virtual scsi and FC mobility preparation functionality + + + ibm,current-associativity-domain property + + + HPT resizing option - KVM only + + + Add Coherent Platform Facilities (CAPI) + + + XIVE Exploitation + + + Add 'OCC online/offline' events to 'IE' error log subsection + + + LPM Redundancy Phase II: Redundancy + + + Add optional sub-queue support to VFC on P9 and newer + + + Increase max num-entries for H_SEND_SUB_CRQ_INDIRECT to 128 + + + Add Virtual Serial Multiplex adapter interfaces + + + Maximum size of Dispatch Trace Log Buffer + + + Eliminate requirement for clearing TCP checksum field for ILLAN checksum calculation + + + Continued Extension of H_Send_Logical_LAN for large send packets + + + Add LPM Capablity keyword to RTAS AIX Support system parameter + + + XIVE Exploitation addition: Add ESB Reset Status to RTAS ibm,read-slot-reset-state2 + + + Add NVDIMM Protection and Encryption State system parameters + + + Change or Remove 0x9 and 0xA event subtypes for 'IE' error log subsection + + + + + Additional, post PAPR 2.9 ACRs as follows: + + + Reserve a range of hcalls to to support Ultravisor + + + Add New CAS Bit For SRIOV Virtual Function (VF) Dynamic DMA Window (DDW) Support + + + Updates to support vTPM 2.0 + + + Update XIVE Legacy hcalls to add H_Function + + + Add NVDIMM Secure Erase Command system parameter + + + Update H_REGISTER_VPA to add H_STATE return code for VPA and SLB shadow buffer. + + + Extend Firmware Assisted Dump for ISA Version 3.0 + + + Add a new return code, H_NOT_AVAILABLE, to start-cpu rtas call + + + Document already-implemented NVRAM variables + + + Update ibm,dynamic-memory-vN flags to include a "Hotplugged Memory" flag + + + + + + + + 2019-01-08 + + + + Revision 0.5_pre4 - Update document type to Work Group Note. Final review ready. + + + + + + 2018-07-30 + + + + Revision 0.5_pre3 - Updates to documentation in preparation for System SW WG review: + + + Reset document version to 0.5 + + + Improved Abstract + + + + + + + + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + + + 2016-05-04 + + + + Revision 2.0_pre1 - initial conversion from IBM document. Extracted from + Linux on Power Architecture Platform Reference (LoPAPR) version 1.1 dated March 24, + 2016 -- Chapter 1 (Introduction), Chapter 2 (System Requirements), + Chapter 3 (Address Map), Chapter 4 (I/O Bridges and Topology), + Chapter 5 (Processors and Memory), Chapter 6 (Interrupt Controller), + Chapter 8 (Non-volatile memory), Chapter 9 (I/O Devices), + Chapter 11 (The Symmetric Multiprocessor Option), Chapter 12 (Product Topology), + and Appendix H (Non-Uniform Memory Access [NUMA] Option). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/common/ch_LoPAR_preface.xml b/LoPAR/ch_LoPAPR_preface.xml similarity index 82% rename from common/ch_LoPAR_preface.xml rename to LoPAR/ch_LoPAPR_preface.xml index 0659d63..de1d7e0 100644 --- a/common/ch_LoPAR_preface.xml +++ b/LoPAR/ch_LoPAPR_preface.xml @@ -1,7 +1,7 @@ About This Document - - - - - + + + + + diff --git a/Platform/ch_address_map.xml b/LoPAR/ch_address_map.xml similarity index 100% rename from Platform/ch_address_map.xml rename to LoPAR/ch_address_map.xml diff --git a/Virtualization/ch_dynamic_reconfig.xml b/LoPAR/ch_dynamic_reconfig.xml similarity index 93% rename from Virtualization/ch_dynamic_reconfig.xml rename to LoPAR/ch_dynamic_reconfig.xml index 7aaa82d..5c93900 100644 --- a/Virtualization/ch_dynamic_reconfig.xml +++ b/LoPAR/ch_dynamic_reconfig.xml @@ -4205,252 +4205,252 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + +
+ Isolation of Coherent Platform Facilities + + Isolation of a Coherent Platform Facility (COPLATFAC) disconnects the OS + image from any of the DR connectors downstream (Coherent Platform Functions or + COPLATFUN) of the Coherent Platform Facility. To avoid the complex- ity of + gracefully managing multi-level isolation, isolation is restricted to only + “leaf” DR connectors, that is connectors that have no unisolated or usable DR + connectors below them. All COPLATFUN connectors must return unusable state (2) + during get-sensor-state before a COPLATFAC can be isolated, this is done through + set-indicator (isolation-state, isolate). The OS is responsible for removing all + memory mappings and detaching all processes potentially in use by co- herent + platform functions. If valid mappings or processes are found, the set-indicator + does not change the isolation state and returns with a Status -9001 (Valid + outstanding translation). + + + + R1--1. + + For all LRDR options: If a + request to set-indicator (isolation-state, isolate) + would result in the isolation of one or more other DR connectors + which are currently unisolated or usable, then the + set-indicator RTAS must fail with a return code of + “Multi-level isolation error” (-9000). + + + + + R1--2. + + For the LRDR option combined with the LPAR + option: The RTAS set-indicator specifying + isolate isolation-state of a COPLATFUN DR connector type must check that + all processes associated with the function are detached, else the RTAS + routine must return with a Status -9001 (Valid outstanding translation) + and the isolation-state is not changed. + + + + +
- -
- Isolation of Coherent Platform Facilities - - Isolation of a Coherent Platform Facility (COPLATFAC) disconnects the OS - image from any of the DR connectors downstream (Coherent Platform Functions or - COPLATFUN) of the Coherent Platform Facility. To avoid the complex- ity of - gracefully managing multi-level isolation, isolation is restricted to only - “leaf” DR connectors, that is connectors that have no unisolated or usable DR - connectors below them. All COPLATFUN connectors must return unusable state (2) - during get-sensor-state before a COPLATFAC can be isolated, this is done through - set-indicator (isolation-state, isolate). The OS is responsible for removing all - memory mappings and detaching all processes potentially in use by co- herent - platform functions. If valid mappings or processes are found, the set-indicator - does not change the isolation state and returns with a Status -9001 (Valid - outstanding translation). +
+ <emphasis>set-indicator</emphasis> (dr-indicator) + Logical connectors do not have associated dr-indicators (token + value 9002). An attempt to set the state of such an indicator results in + a “No such indicator implemented” return status. + - - R1- + R1--1. - For all LRDR options: If a - request to set-indicator (isolation-state, isolate) - would result in the isolation of one or more other DR connectors - which are currently unisolated or usable, then the - set-indicator RTAS must fail with a return code of - “Multi-level isolation error” (-9000). - - - - - R1--2. - - For the LRDR option combined with the LPAR - option: The RTAS set-indicator specifying - isolate isolation-state of a COPLATFUN DR connector type must check that - all processes associated with the function are detached, else the RTAS - routine must return with a Status -9001 (Valid outstanding translation) - and the isolation-state is not changed. + For all LRDR options: The calling of + set-indicator with a token value of 9002 + (dr-indicator) and an index representing a logical connector must fail + with a return code of “No such indicator implemented” + (-3). - + +
-
- -
- <emphasis>set-indicator</emphasis> (dr-indicator) - Logical connectors do not have associated dr-indicators (token - value 9002). An attempt to set the state of such an indicator results in - a “No such indicator implemented” return status. - - - - - R1--1. - - For all LRDR options: The calling of - set-indicator with a token value of 9002 - (dr-indicator) and an index representing a logical connector must fail - with a return code of “No such indicator implemented” - (-3). - - - -
- -
- <emphasis>ibm,configure-connector</emphasis> - The - ibm,configure-connector RTAS call is used to return - to the OS the device tree nodes and properties associated with the newly - un-isolated logical resources and configure them for use. - The - ibm,configure-connector RTAS call used against a - logical DR connector can encounter other logical DR connectors or - physical DR connectors below it in the tree. If a logical connector is - encountered below a logical connector that is being configured, the - ibm,configure-connector RTAS call will not configure - the sub-tree, if it is not owned by the OS (where owned refers to a DR - connector that would return a DR entity usable, for a - get-sensor dr-entity-sense sensor). If a physical - connector is encountered, then the sub-tree below the physical connector - may or may not be configured, depending on the implementation. - - Architecture Note: The requirements of this section - specify the minimum sub-tree contents returned for various connector - types. Implementations may optionally return other valid previously - reported nodes that represent the current configuration of the device - tree. Previously reported nodes may not have any changes from their - previously reported state. A node that was removed from the configuration - due to a DR operation and returns due to a subsequent DR operation is not - considered to have been previously reported. It is the caller's - responsibility to recognize previously reported nodes. +
+ <emphasis>ibm,configure-connector</emphasis> + The + ibm,configure-connector RTAS call is used to return + to the OS the device tree nodes and properties associated with the newly + un-isolated logical resources and configure them for use. + The + ibm,configure-connector RTAS call used against a + logical DR connector can encounter other logical DR connectors or + physical DR connectors below it in the tree. If a logical connector is + encountered below a logical connector that is being configured, the + ibm,configure-connector RTAS call will not configure + the sub-tree, if it is not owned by the OS (where owned refers to a DR + connector that would return a DR entity usable, for a + get-sensor dr-entity-sense sensor). If a physical + connector is encountered, then the sub-tree below the physical connector + may or may not be configured, depending on the implementation. + + Architecture Note: The requirements of this section + specify the minimum sub-tree contents returned for various connector + types. Implementations may optionally return other valid previously + reported nodes that represent the current configuration of the device + tree. Previously reported nodes may not have any changes from their + previously reported state. A node that was removed from the configuration + due to a DR operation and returns due to a subsequent DR operation is not + considered to have been previously reported. It is the caller's + responsibility to recognize previously reported nodes. - - - R1--1. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector that is - isolated, - ibm,configure-connector must immediately return - configuration complete. - - + + + R1--1. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector that is + isolated, + ibm,configure-connector must immediately return + configuration complete. + + - - R1--2. - - For all LRDR options: If the connector index refers - to a connector that would return a “DR entity unusable” - status (2), “DR entity available for exchange” status (3), or - “DR entity available for recovery” status (4) to the - get-sensor dr-entity-sense token, the - ibm,configure-connector RTAS call must return - “-9003: Cannot configure - Logical DR connector unusable, available - for exchange, or available for recovery” on the first call without - any configuration action taken on the DR connector. - - + + R1--2. + + For all LRDR options: If the connector index refers + to a connector that would return a “DR entity unusable” + status (2), “DR entity available for exchange” status (3), or + “DR entity available for recovery” status (4) to the + get-sensor dr-entity-sense token, the + ibm,configure-connector RTAS call must return + “-9003: Cannot configure - Logical DR connector unusable, available + for exchange, or available for recovery” on the first call without + any configuration action taken on the DR connector. + + - - R1--3. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector of type - CPU, - the returned sub-tree must consist of the specific - cpu-node, its children, and any referenced nodes that had not been - previously reported (such as L2 and L3 caches etc.) all containing the - properties as would be contained in those nodes had they been available - at boot time. - - Implementation Note: Future platforms that support - concurrent maintenance of caches, will require that high level cache - nodes (L2, L3 etc.) are added by - ibm,configure-connector such that their properties - can change as new/repaired hardware is added to the platform. Therefore, - it is the OS's responsibility when isolating a CPU to purge any - information it may have regarding an orphaned high level cache node. The - OS may use the - “ibm,phandle” property to selectively - remove caches when a processor is removed. The platform considers any - high level cache that is newly referenced (reference count for this - partition goes from 0 to 1) to have been previously unreported. - - + + R1--3. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of type + CPU, + the returned sub-tree must consist of the specific + cpu-node, its children, and any referenced nodes that had not been + previously reported (such as L2 and L3 caches etc.) all containing the + properties as would be contained in those nodes had they been available + at boot time. + + Implementation Note: Future platforms that support + concurrent maintenance of caches, will require that high level cache + nodes (L2, L3 etc.) are added by + ibm,configure-connector such that their properties + can change as new/repaired hardware is added to the platform. Therefore, + it is the OS's responsibility when isolating a CPU to purge any + information it may have regarding an orphaned high level cache node. The + OS may use the + “ibm,phandle” property to selectively + remove caches when a processor is removed. The platform considers any + high level cache that is newly referenced (reference count for this + partition goes from 0 to 1) to have been previously unreported. + + - - R1--4. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector of type - MEM, - the returned sub-tree must consist of the specific - ibm,memory-region node containing the properties as - would be contained in that node had it been available at boot - time. - - + + R1--4. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of type + MEM, + the returned sub-tree must consist of the specific + ibm,memory-region node containing the properties as + would be contained in that node had it been available at boot + time. + + - - R1--5. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector of type - PHB or SLOT, then all of the following must be true: - - - The returned values must represent the sub-tree for the specific - I/O sub-system represented by the connector, except for entities below - any DR connectors (logical or physical) which are below the connector - which is the target of the ibm,configure-connector operation (that is, - the ibm,configure-connector operation stops at any DR connector). - + + R1--5. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of type + PHB or SLOT, then all of the following must be true: + + + The returned values must represent the sub-tree for the specific + I/O sub-system represented by the connector, except for entities below + any DR connectors (logical or physical) which are below the connector + which is the target of the ibm,configure-connector operation (that is, + the ibm,configure-connector operation stops at any DR connector). + - - The sub-tree must consist of the specific node and its children - all containing the properties as would be contained in those nodes had - they been available at boot time, including (if they exist) built-in PCI - IOAs. - - - - - + + The sub-tree must consist of the specific node and its children + all containing the properties as would be contained in those nodes had + they been available at boot time, including (if they exist) built-in PCI + IOAs. + + + + + - - R1--6. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector of type - SLOT, - the returned values must represent the sub-tree for - the specific I/O sub-system represented by the SLOT connector, and the - sub-tree must consist of the specific - /pci node and its children all containing the - properties as would be contained in those nodes had they been available - at boot time, except for the PCI IOA nodes assigned to the OS image that - contain the same properties as they would following a PCI hot plug - operation (see - ). - - + + R1--6. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of type + SLOT, + the returned values must represent the sub-tree for + the specific I/O sub-system represented by the SLOT connector, and the + sub-tree must consist of the specific + /pci node and its children all containing the + properties as would be contained in those nodes had they been available + at boot time, except for the PCI IOA nodes assigned to the OS image that + contain the same properties as they would following a PCI hot plug + operation (see + ). + + - - R1--7. - - For all LRDR options: If a platform implementation - powers-up and configures physical DR entities in the sub-tree under a - logical DR connector, then a request to - ibm,configure-connector of the logical DR connector - must use the return status of 990x from the - ibm,configure-connector call, as necessary, during - the DR entity power-up sequence(s) and must control any power-up and - sequencing requirements, as would be done by the platform during platform - power-up. - - + + R1--7. + + For all LRDR options: If a platform implementation + powers-up and configures physical DR entities in the sub-tree under a + logical DR connector, then a request to + ibm,configure-connector of the logical DR connector + must use the return status of 990x from the + ibm,configure-connector call, as necessary, during + the DR entity power-up sequence(s) and must control any power-up and + sequencing requirements, as would be done by the platform during platform + power-up. + + - - R1--8. - - For all LRDR options: If a request to - ibm,configure-connector specifies a connector of - type CO- PLATFAC or COPLATFUN, the returned values must represent the - sub-tree for the specific coherent plat- form sub-system represented by - the COPLATFAC or COPLATFUN connector. All properties are updated with - the most recent data from the coherent platform resource. - - - + + R1--8. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of + type CO- PLATFAC or COPLATFUN, the returned values must represent the + sub-tree for the specific coherent plat- form sub-system represented by + the COPLATFAC or COPLATFUN connector. All properties are updated with + the most recent data from the coherent platform resource. + + + +
diff --git a/Platform/ch_interrupt_controller.xml b/LoPAR/ch_interrupt_controller.xml similarity index 100% rename from Platform/ch_interrupt_controller.xml rename to LoPAR/ch_interrupt_controller.xml diff --git a/Platform/ch_platform_intro.xml b/LoPAR/ch_introduction.xml similarity index 100% rename from Platform/ch_platform_intro.xml rename to LoPAR/ch_introduction.xml diff --git a/Platform/ch_io_devices.xml b/LoPAR/ch_io_devices.xml similarity index 100% rename from Platform/ch_io_devices.xml rename to LoPAR/ch_io_devices.xml diff --git a/Platform/ch_io_topology.xml b/LoPAR/ch_io_topology.xml similarity index 100% rename from Platform/ch_io_topology.xml rename to LoPAR/ch_io_topology.xml diff --git a/Virtualization/ch_lpar_option.xml b/LoPAR/ch_lpar_option.xml similarity index 100% rename from Virtualization/ch_lpar_option.xml rename to LoPAR/ch_lpar_option.xml diff --git a/Platform/ch_nonvolatile_memory.xml b/LoPAR/ch_nonvolatile_memory.xml similarity index 100% rename from Platform/ch_nonvolatile_memory.xml rename to LoPAR/ch_nonvolatile_memory.xml diff --git a/Error Handling/ch_notifications.xml b/LoPAR/ch_notifications.xml similarity index 79% rename from Error Handling/ch_notifications.xml rename to LoPAR/ch_notifications.xml index ceea70c..7774d9d 100644 --- a/Error Handling/ch_notifications.xml +++ b/LoPAR/ch_notifications.xml @@ -1,7 +1,7 @@ - + Error and Event Notification - + - - + + + diff --git a/Platform/ch_numa.xml b/LoPAR/ch_numa.xml similarity index 100% rename from Platform/ch_numa.xml rename to LoPAR/ch_numa.xml diff --git a/Platform/ch_processors_memory.xml b/LoPAR/ch_processors_memory.xml similarity index 100% rename from Platform/ch_processors_memory.xml rename to LoPAR/ch_processors_memory.xml diff --git a/Platform/ch_product_topology.xml b/LoPAR/ch_product_topology.xml similarity index 96% rename from Platform/ch_product_topology.xml rename to LoPAR/ch_product_topology.xml index 0aeafea..8c8aa71 100644 --- a/Platform/ch_product_topology.xml +++ b/LoPAR/ch_product_topology.xml @@ -1594,177 +1594,177 @@ xml:lang="en"> - -
- Resource Location Codes - - The resource location label consists of the - prefix 'R' followed by a non-zero decimal number. A - resource location code identifies a chip or function - embedded on a FRU. There may be multiple - resources associated with a FRU. The numbering of the - resources on a particular FRU should match - the left to right, top to bottom positioning of the - resources on the FRU when the FRU is in a typical - service position. - - It should be noted that embedded adapters with - internal ports existed prior to introduction of the - resource label. Use of the resource label for unique - partitionable endpoint identification may or may - not be retrofitted to those adapters as they are - carried forward to new platforms. -
+
+ Resource Location Codes + + The resource location label consists of the + prefix 'R' followed by a non-zero decimal number. A + resource location code identifies a chip or function + embedded on a FRU. There may be multiple + resources associated with a FRU. The numbering of the + resources on a particular FRU should match + the left to right, top to bottom positioning of the + resources on the FRU when the FRU is in a typical + service position. + + It should be noted that embedded adapters with + internal ports existed prior to introduction of the + resource label. Use of the resource label for unique + partitionable endpoint identification may or may + not be retrofitted to those adapters as they are + carried forward to new platforms. +
-
- Multiple FRUs In The Same Physical Space - - A physical location code is tied to the connector - that a FRU plugs into. If two different parts with - different part numbers can plug into the same connector, - both parts will have the same location code. - However, if two different parts can plug into two - different connectors but share the same physical - space when either is installed, those parts should - each have a different location code. For example, if - two different GX adapters (such as the Bjorn IB adapter - and Newcombe PCI slot riser on Jupiter-IOC) - connect to the same planar using the same connector, - they should both be assigned the same location - code. But if a GX adapter or a PCI adapter can be - installed on a planar, but not both at the same time - as they both can't fit at the same time given the - placement of the connectors on the planar, both slots - should be assigned unique location codes. -
+
+ Multiple FRUs In The Same Physical Space + + A physical location code is tied to the connector + that a FRU plugs into. If two different parts with + different part numbers can plug into the same connector, + both parts will have the same location code. + However, if two different parts can plug into two + different connectors but share the same physical + space when either is installed, those parts should + each have a different location code. For example, if + two different GX adapters (such as the Bjorn IB adapter + and Newcombe PCI slot riser on Jupiter-IOC) + connect to the same planar using the same connector, + they should both be assigned the same location + code. But if a GX adapter or a PCI adapter can be + installed on a planar, but not both at the same time + as they both can't fit at the same time given the + placement of the connectors on the planar, both slots + should be assigned unique location codes. +
-
- PCI-E Attached I/O Drawers - - A PCI-E attached I/O drawer is an I/O drawer that - attaches to a GX adapter in the CEC via PCI-E - cables (as opposed to RIO or IB cables). There are two - different types of PCI-E attached I/O drawers: - ones where PHB(s) on the GX adapter connect directly - to I/O devices in the drawer and ones where the - PHB(s) on the GX adapter connect to switches (or other - fan-out logic) in the I/O drawer. In the former - case, the partitionable endpoint (PE) is the logical - PHB connection to the device. In the latter case, the - PEs are the slots wired to the downstream switch ports. - - For GX cards whose PHBs connect directly to - devices in the I/O drawer (such as Bluehawk), the - location code and DRC name of the I/O slot partitionable - endpoint will be of the form Ucec-Pw-Cx- - Ty-Lz. Here, Ucec is the type/model/serial of the CEC - that contains the GX adapter, Pw is the planar - that contains the GX adapter, Cx is the GX adapter, - Ty is one of the ports on the adapter, and Lz is a - logical label representing a logical PCI-e connection - to an I/O device at the other end of the PCI-e - cable plugged into that port (note that there may be - multiple Cx labels if the GX adapter doesn't plug - directly into the planar in the system in question). - This location code and DRC name will be generated - by system firmware for each PE on each GX adapter that - is installed in the system and that supports - direct-connect drawers (i.e. drawers without a PCI-E - switch in them). The location code and DRC - name will be generated regardless of whether or not a - PCI-E cable is attached to the GX adapter. - It is permissible to append additional labels beyond - the L label to create different location codes for - FRUs/devices downstream from the I/O device in the - drawer that is attached to the PCI-e cable. It is - not required that all subsequent labels be logical labels. - - For GX cards whose ports connect to a PCI-E switch - in an I/O drawer via PCI-E cables, the location - code format has not yet been defined. -
+
+ PCI-E Attached I/O Drawers + + A PCI-E attached I/O drawer is an I/O drawer that + attaches to a GX adapter in the CEC via PCI-E + cables (as opposed to RIO or IB cables). There are two + different types of PCI-E attached I/O drawers: + ones where PHB(s) on the GX adapter connect directly + to I/O devices in the drawer and ones where the + PHB(s) on the GX adapter connect to switches (or other + fan-out logic) in the I/O drawer. In the former + case, the partitionable endpoint (PE) is the logical + PHB connection to the device. In the latter case, the + PEs are the slots wired to the downstream switch ports. + + For GX cards whose PHBs connect directly to + devices in the I/O drawer (such as Bluehawk), the + location code and DRC name of the I/O slot partitionable + endpoint will be of the form Ucec-Pw-Cx- + Ty-Lz. Here, Ucec is the type/model/serial of the CEC + that contains the GX adapter, Pw is the planar + that contains the GX adapter, Cx is the GX adapter, + Ty is one of the ports on the adapter, and Lz is a + logical label representing a logical PCI-e connection + to an I/O device at the other end of the PCI-e + cable plugged into that port (note that there may be + multiple Cx labels if the GX adapter doesn't plug + directly into the planar in the system in question). + This location code and DRC name will be generated + by system firmware for each PE on each GX adapter that + is installed in the system and that supports + direct-connect drawers (i.e. drawers without a PCI-E + switch in them). The location code and DRC + name will be generated regardless of whether or not a + PCI-E cable is attached to the GX adapter. + It is permissible to append additional labels beyond + the L label to create different location codes for + FRUs/devices downstream from the I/O device in the + drawer that is attached to the PCI-e cable. It is + not required that all subsequent labels be logical labels. + + For GX cards whose ports connect to a PCI-E switch + in an I/O drawer via PCI-E cables, the location + code format has not yet been defined. +
-
- Virtual SCSI (vSCSI) Device Location Codes - - The location code for a virtual SCSI (vSCSI) - device is formed by appending an L label to the location - code of the parent virtual IOA. The L label contains a - 48 or 64 bit hexadecimal value that uniquely - identifies the virtualized SCSI device. A virtual - SCSI device attached to a virtual IOA at - U9119.MME.1085B17-V4-C5-T1 would have a location code of the form: - U9119.MME.1085B17-V4-C5-T1-L8100000000000000 - Note that some old pSeries firmware may represent - the virtualized device identifier as - W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in - late 2008. - - See for a description of the - virtual IOA location code. -
+
+ Virtual SCSI (vSCSI) Device Location Codes + + The location code for a virtual SCSI (vSCSI) + device is formed by appending an L label to the location + code of the parent virtual IOA. The L label contains a + 48 or 64 bit hexadecimal value that uniquely + identifies the virtualized SCSI device. A virtual + SCSI device attached to a virtual IOA at + U9119.MME.1085B17-V4-C5-T1 would have a location code of the form: + U9119.MME.1085B17-V4-C5-T1-L8100000000000000 + Note that some old pSeries firmware may represent + the virtualized device identifier as + W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in + late 2008. + + See for a description of the + virtual IOA location code. +
-
- Virtual Fibre Channel Device Location Codes +
+ Virtual Fibre Channel Device Location Codes - The location code for a virtual fibre channel device - is formed by appending the worldwide unique port - identifier (W label) and LUN (L label) to the location - code of the parent virtual IOA. The values of - the L and W labels are both in hexadecimal. A fibre - channel disk attached to a virtual IOA at - U9119.MME.1085B17-V4-C5-T1 would have a location - code of the form: + The location code for a virtual fibre channel device + is formed by appending the worldwide unique port + identifier (W label) and LUN (L label) to the location + code of the parent virtual IOA. The values of + the L and W labels are both in hexadecimal. A fibre + channel disk attached to a virtual IOA at + U9119.MME.1085B17-V4-C5-T1 would have a location + code of the form: - - - U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000 - - + + + U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000 + + - See for a description of the - virtual IOA location code. -
+ See for a description of the + virtual IOA location code. +
-
- NVMe Device Logical Path Location Codes +
+ NVMe Device Logical Path Location Codes - Non-volatile memory (NVM) devices that are - not mounted/docked on a backplane that supports - location code VPD will have location codes composed - of the location code of the controlling IOA - followed by a L label. The number value of L label - is a decimal value, and it is the unique NVMe - namespace identifier. An NVMe device controlled by - an IOA at U787A.001.1012345-P1-C5 would - have a location code of the form: + Non-volatile memory (NVM) devices that are + not mounted/docked on a backplane that supports + location code VPD will have location codes composed + of the location code of the controlling IOA + followed by a L label. The number value of L label + is a decimal value, and it is the unique NVMe + namespace identifier. An NVMe device controlled by + an IOA at U787A.001.1012345-P1-C5 would + have a location code of the form: - - - U787A.001.1012345-P1-C5-L3 - - -
+ + + U787A.001.1012345-P1-C5-L3 + + +
-
- Virtual Coherent Accelerator (CAPI) Function Location Codes +
+ Virtual Coherent Accelerator (CAPI) Function Location Codes - The location code for a virtual coherent accelerator - (CA) function is formed by appending two S labels, - the first specifying the identifier of the physical - function and the second specifying the identifier of the - logical function, both in decimal, to the location code of - the physical CAPI adapter. A virtual CA - function associated with physical function 1 and logical - function 2 on the CAPI adapter at location - U78CA.001.1234567-P1-C4-C1 would have location code: + The location code for a virtual coherent accelerator + (CA) function is formed by appending two S labels, + the first specifying the identifier of the physical + function and the second specifying the identifier of the + logical function, both in decimal, to the location code of + the physical CAPI adapter. A virtual CA + function associated with physical function 1 and logical + function 2 on the CAPI adapter at location + U78CA.001.1234567-P1-C4-C1 would have location code: - - - U78CA.001.1234567-P1-C4-C1-S1-S2 - - + + + U78CA.001.1234567-P1-C4-C1-S1-S2 + + +
diff --git a/LoPAR/ch_rtas.xml b/LoPAR/ch_rtas.xml new file mode 100644 index 0000000..9f26646 --- /dev/null +++ b/LoPAR/ch_rtas.xml @@ -0,0 +1,30 @@ + + + + + Run-Time Abstration Services + + + + + + + diff --git a/Error Handling/app_service_indicators.xml b/LoPAR/ch_service_indicators.xml similarity index 90% rename from Error Handling/app_service_indicators.xml rename to LoPAR/ch_service_indicators.xml index ec29a5b..13201f5 100644 --- a/Error Handling/app_service_indicators.xml +++ b/LoPAR/ch_service_indicators.xml @@ -1,7 +1,7 @@ - Service Indicators - + This chapter defines service indicators Note that many times “indicators” are referred to as “LEDs” as this is one of the most common implementations for indicators at the current time. relative to: - + Which service indicators may be exposed to an OS and which may @@ -41,37 +41,37 @@ are exposed to the OS or not - +
General This section gives some general background information required to understand the service indicator requirements. The service indicator - requirements can be found starting in + requirements can be found starting in .
Basic Platform Definitions The following are the definitions of some of the terms used in this - architecture. See also + architecture. See also for additional terms. - +
“Enclosure”, Packaging, and Other Terminology In order to abstract specific packaging differences between different products, this architecture uses a number of terms that denote a unit of packaging. - The term + The term enclosure means something different, depending on the product line. Generally this is an entity that can be unplugged and be removed from the system, but may include the entire system, and generally encloses other FRUs. It is, however, possible to have a FRU that contains - + one other FRU, and not have it be an enclosure. See below, for more information. The concept of the enclosure is very key to this architecture, because the enclosure provides the anchor point for the Enclosure Fault, - Enclosure Identify, and (when applicable) the Error Log indicators. + Enclosure Identify, and (when applicable) the Error Log indicators. @@ -79,87 +79,87 @@ sidecars. - A sidecar is a blade that plugs + A sidecar is a blade that plugs into a blade slot, but which is physically connected to the base blade and which cannot be removed without also removing the base blade and any other attached sidecars. - + The Enclosure Identify indicator is located on the base blade. Sidecars do not have an Enclosure Identify indicator. - + A stand-alone computing box, like a deskside unit. - + A separately powered box that attaches to a stand-alone computing box (for example, an I/O expansion tower). - + For a rack system, a drawer or partial drawer, with its own power domains, within a rack system (but not a chassis, in blade system terms). - + FRUs that have one or no internal FRUs are a possible exception to the above definition of enclosure. The general requirements are that the - enclosing FRU does not need an Error Log indicator (see also Requirement + enclosing FRU does not need an Error Log indicator (see also Requirement ), implements the full xipSIA - Lightpath architecture + Lightpath architecture including FRU Identify, has the enclosing FRU Fault/Identify and internal (if any) FRU Fault/Identify indicators visible from the outside of the system the same way that enclosure indicators would be, and rolls-up the FRU Fault/Identify indicators to the next level of indicators when there is a next level (for example, chassis level indicators). Examples of the type of FRUs that the xipSIA - architecture team + architecture team might approve as a non-enclosures is: - + Appliance drawers (“appliance” means that there are no field serviceable parts inside). - + Appliance Blades, except if they require an Error Log indicator. - + A power supply which comprises two or fewer FRUs. - + Fans, but not fan assemblies when the fan assemblies have three or more Fault indicators. - - In addition, the term - System Enclosure (also known as a + + In addition, the term + System Enclosure (also known as a Primary Enclosure) is used to denote the enclosure of a system that contains the one and only Error Log indicator Previously known as the System Information (Attention) indicator. for the system. An enclosure that is not a System Enclosure is - called a + called a secondary enclosure. The System Enclosure is expected to be one that contains at least some of the system processors for the platform. - - In this chapter, the term + + In this chapter, the term chassis will refer to a blade system chassis. - + Other terminology used in this chapter includes: @@ -172,15 +172,15 @@ example a second request to activate an already active indicator, is also considered to be an activation of that indicator). - - + + active state An indicator in an active state is in a non-off state. Different indicator types can be set to a different set of active states. For each of the following indicators, the following states are applicable - in the indicator active state (See + in the indicator active state (See for more detail on when each state is applicable and for the conditions under which a state transition is made): @@ -192,17 +192,17 @@ Blue Rack Identify: on Blue Row Identify: on - + blip A blink state with a short duty cycle used in the “remind” state for Enclosure Fault Indicators. See also - Requirement + Requirement . - + Chassis Enclosure Identify @@ -210,14 +210,14 @@ An Enclosure Identify indicator at the blade system chassis level. - + CRU See FRU. - + deactivate @@ -225,10 +225,10 @@ To deactivate an indicator (physical or virtual) means to set it to the off state. Deactivating a virtual indicator may or may not deactivate the physical indicator associated with that virtual - indicator (see + indicator (see ). - + Enclosure Fault @@ -237,7 +237,7 @@ that there is a FRU Fault indicator in the enclosure that is active. - + Enclosure Identify @@ -246,7 +246,7 @@ enclosure in an installation or an enclosure in a group. This indicator is blue in color and is turned on in the active identify state. - + FRU @@ -254,7 +254,7 @@ Field Replaceable Unit. Used to also mean CRU (Customer Replaceable Unit) in this chapter. - + FRU Fault @@ -262,7 +262,7 @@ An amber indicator that is used to point to a failing FRU in an enclosure. - + FRU Identify @@ -271,41 +271,41 @@ an enclosure or a place where a FRU is to be plugged (for example, for an upgrade operation). - - + + Guiding Light Mode A platform implementation that provides FRU - Identify indicators for identifying failing FRUs. See + Identify indicators for identifying failing FRUs. See for more information. - - + + ID Shorthand used some places (mainly figures) in this chapter for “Identify” or “Identify indicator”. - - + + Lightpath Mode A platform implementation that provides FRU Fault - indicators as the general way to identify failing FRUs. See + indicators as the general way to identify failing FRUs. See for more information. - - + + not visible to the OS See transparent to the OS. - - + + primary level indicators @@ -313,8 +313,8 @@ example, for rack systems, the enclosure is either the blade, for blade systems, or the drawer level, for non-blade systems. - - + + roll-down @@ -324,8 +324,8 @@ indicator. This architecture will use roll-up for both activation and deactivation. See roll-up. - - + + roll-up @@ -337,24 +337,24 @@ in an enclosure is deactivated, the Enclosure Fault indicator for that enclosure is deactivated. - - + + secondary level indicators The indicators on levels below the Primary Level and above the FRU level. - - + + SFP - Service Focal Point. See also + Service Focal Point. See also . - - + + Error Log @@ -362,15 +362,15 @@ the error log or problem determination procedures, in order to determine the cause. - - + + tertiary level indicators The FRU level indicators. - - + + transparent to the OS @@ -378,19 +378,19 @@ sensed by OS or application level software. For example, power supply Fault indicators. - - + + turn off To turn off a physical indicator means exactly like it sounds. Turning off a virtual or logical indicator may or may not turn off the physical indicator, depending on the state diagram for the - physical one (see + physical one (see ). - - + + visible to the OS @@ -398,11 +398,11 @@ by OS or application level software. For PCI Hot Plug indicators. See also . - + - +
- +
Service Indicator Visibility and Transparency to the OS @@ -412,25 +412,25 @@ said to be visible to the OS when its state can be modified and sensed by OS or application level software (for example, PCI Hot Plug indicators). - Requirements on visibility can be found in + Requirements on visibility can be found in .
- +
Service Indicator - A + A service indicator is defined as any indicator that is used in the course of servicing a system. The intent of service - indicators is + indicators is not, in general, to increase system Error Detection and Fault Isolation (EDFI), but rather to guide the user in performance of a service action. Usages include (but are not limited to): - + Dynamic Reconfiguration (LoPAR indicator type 9002) to indicate the status of DR operations on a Field Replacable Unit (FRU). More - information on DR indicators can be found in + information on DR indicators can be found in . This indicator is amber The term “amber” will be used in this chapter to mean @@ -439,7 +439,7 @@ this indicator with the power indicator, where the color was green. - + An indication of a fault condition of a FRU (LoPAR indicator type 9006, when OS visible). This indicator is amber in color. The FRU @@ -456,23 +456,23 @@ indicator, will be available to the software that handles serviceable events. - + For Lightpath Mode platforms, a FRU fault indicator will be available to the software and is activated by the detector of the error. In addition, the FRU Fault rolls up to an Enclosure Fault indicator. - + - + A system-wide indication of a fault or some condition needing attention in the system. An Error Log indicator (LoPAR indicator type 9006) is an example of an OS-visible For a definition of the visibility or transparency of an - indicator, see + indicator, see . indicator of this class of indicators. The Error Log indicator is a flag to the user that there is something in the system needing @@ -495,7 +495,7 @@ this class. These indicators may or may not be visible to an OS. In this capacity, the indicator is activated - For a definition of what “activate” means, see + For a definition of what “activate” means, see . at the user’s request in order to help them locate a component in the system (for example, a FRU, a connector, an enclosure, @@ -519,30 +519,30 @@ Hardware only indicators such as Ethernet activity indicators. These are transparent to the OS. - - + +
- +
Service Indicator Modes There are two modes that a platform can operate in relative to service indicators: Lightpath Mode and Guiding Light Mode. Any particular - + platform operates in one and only one mode relative - to service indicators: Lightpath Mode or Guiding Light Mode. A + to service indicators: Lightpath Mode or Guiding Light Mode. A component (hardware, firmware, or software) which is designed to be used in both a Lightpath Mode and a Guiding Light Mode platform needs to be able to operate in both modes. For guidance in which mode a platform should be designed to - operate, see + operate, see . The following sections give an overview of these two modes. For - specific requirements of each mode, see + specific requirements of each mode, see .
Lightpath Mode - The + The Lightpath Mode specifies a platform implementation of service indicators much like what industry-standard servers originally implemented with its Lightpath, except that FRU indicators also implement @@ -550,7 +550,7 @@ overrides the Fault state while the Identify is active for an indicator, and the indicator is put into the Fault state, if one is pending, when the Identify is removed. - A summary of the Lightpath Mode is as follows (see + A summary of the Lightpath Mode is as follows (see for detailed requirements): @@ -577,7 +577,7 @@ part of the FRU. In the latter case, this represents a shared FRU, in which case the FRU Fault indicator is virtualized, so that one partition cannot view the setting by another partition, which would allow a covert - storage channel (see also + storage channel (see also ). @@ -597,7 +597,7 @@ running on the OS. In the partially owned case, this represents a shared FRU, in which case the FRU Identify indicator is virtualized, so that one partition cannot view the setting by another partition, which would allow - a covert storage channel (see also + a covert storage channel (see also ). @@ -620,23 +620,23 @@ The Error Log indicator or virtual copy thereof (for LPARed platforms) is available to each OS image. - - - See Requirement + + + See Requirement for more information for requirements on activation of the Fault indicators. The Triple-S UI, when implemented, also adds additional requires to - Lightpath Mode implementations. See + Lightpath Mode implementations. See .
- +
Guiding Light Mode - A summary of the Guiding Light Mode is as follows (see + A summary of the Guiding Light Mode is as follows (see for detailed requirements): - + FRU Identify indicators are used as the way of identifying service procedures like repair, reconfiguration, and upgrade. FRU @@ -682,15 +682,15 @@ The Error Log indicator, or a virtual copy thereof (for LPARed platforms), is available to the OS. - - + +
- +
Covert Storage Channels - A + A covert storage channel is a path between two entities that can be used to pass data outside the normal data sharing paths like LANs. For example, if two OS images were given access to the same @@ -700,7 +700,7 @@ back and forth. This cannot be allowed, for security reasons, and therefore this architecture defines the concept of virtual indicators. - A + A virtual indicator is provided to each OS image for each physical indicator that is shared between OS images. The physical indicator is activated when any virtual indicator for that physical @@ -709,7 +709,7 @@ general OS image can sense what it is trying to set the indicator to, but cannot sense what the other virtual indicators are set to, and hence no covert storage channel exists. The exception to the shared access is by a - trusted Service Focal Point (see + trusted Service Focal Point (see for more details). For more information on how virtual indicators affect the physical indicator state, see the physical indicator state diagrams later in this @@ -725,10 +725,10 @@ Error Log indicator if the partition in which the OS resides abnormally terminates.
- +
Service Focal Point (SFP) and Service Partition - The + The Service Focal Point (SFP), when it exists, will ultimately be the exclusive common point of control in the system for handling all service actions which are not resolved otherwise (for @@ -744,10 +744,10 @@ indicator. If the SFP in a partitioned system were to be implemented on an OS image that runs non-trusted applications, then the SFP partition could not be given access to the physical and other OS’ virtual - service indicators, or covert storage channels would exist (see + service indicators, or covert storage channels would exist (see ) between the SFP partition and the other OS partitions. This architecture assumes that the SFP is - implemented as trusted or + implemented as trusted or privileged entity which does not allow non-trusted applications running on the same OS image as the SFP, and therefore covert storage channels are not considered to exist between the @@ -757,13 +757,13 @@ to the platform via firmware interfaces, or an external system management entity, are examples of such implementations. For Lightpath Mode, the Triple-S UI is a user interface that is - associated with a SFP. See + associated with a SFP. See . The platform’s physical indicators are accessible to the SFP through the normal indicator interface (LoPAR indicator types 9006 and 9007).
- +
Logical Indicators vs. Physical Indicators A physical indicator is, in many cases, used to represent several @@ -778,18 +778,18 @@ virtual indicator, and may not be even able to sense the state of the physical indicator (that is, can only sense the state of their logical or virtual ones). - The physical indicator state diagrams in + The physical indicator state diagrams in indicate how logical and - virtual indicators are merged into the physical ones. See also + virtual indicators are merged into the physical ones. See also relative to virtual indicators.
- +
Machine Classes and Service Strategy Two broad classifications of computer implementations are defined - here for purposes of defining service indicator implementations. + here for purposes of defining service indicator implementations. shows the comparison of these classes.   @@ -924,16 +924,16 @@
- + Determining whether a platform’s classification, and therefore the service mode of the platform is dependent on the product requirements, and is beyond the scope of this architecture, but might include: - - + + The RAS requirements for the platform. The considerations for - this come from + this come from . @@ -947,8 +947,8 @@ platform’s mode of operation be the Lightpath Mode for that reason. - - + +
General Information about Service Indicators @@ -961,7 +961,7 @@ without removing covers, components, etc. In this case, there is required to be one or more indicators that are higher in the hierarchy which get activated in conjunction with the target indicator. This functionality is - called indicator + called indicator roll-up. Due to the hierarchy, there might be multiple indicators that get rolled-up into a single indicator. The platform (not the OS) is responsible for indicator roll-up. An example of @@ -973,7 +973,7 @@ used here. Also note that an enclosure might be a drawer in a rack or might be part of a drawer. For example, some I/O drawers consist of two separate and independent enclosures. So, sometimes there may be - multiple enclosure indicators per rack drawer. See also + multiple enclosure indicators per rack drawer. See also . in a rack there is a summary LED that summarizes the Identify LEDs within or on the back of the enclosure in a rack, and then the @@ -1048,12 +1048,12 @@ can be used to assist with such things as identifying where an upgrade should be inserted. The general rules for activation and deactivation of indicators can - be found in Requirements - and + be found in Requirements + and , and more explicit - requirements of individual indicators in the state diagrams in + requirements of individual indicators in the state diagrams in . When the Triple-S UI is - implemented, see also + implemented, see also . This architecture assumes that the control of multiple users doing identify operations at the same time, is under procedural control, and is @@ -1071,8 +1071,8 @@ Secondary Light Panels A secondary light panel may be used to house roll-up indicators as indicated in the “intermediate” level or - “secondary” level indicators in - and + “secondary” level indicators in + and . These panels may also house other indicators which would otherwise not have a home (for example, an over-temperature indicator). @@ -1112,13 +1112,13 @@ when that is complete, to put this indicator into the Identify state (on solid).
- +
System-Level Diagrams The following figures are conceptual diagrams showing indicator roll-ups: - - + + . @@ -1130,9 +1130,9 @@ . - - - + + +
Representation of the Indicators -- Lightpath Mode Platform @@ -1146,7 +1146,7 @@
- +
Representation of the Indicators -- Guiding Light Mode Platform @@ -1174,23 +1174,23 @@
- Note: Guiding Light Mode platform shown, + Note: Guiding Light Mode platform shown, with optional Enclosure Fault indicators. For Lightpath Mode platforms, - FRU Fault indicators would always exist and would roll up to the Enclosure - Fault indicator, and additionally, the Rack and Row Identify indicators would - have an additional Fault indicator (not shown) and the Fault indicators at the + FRU Fault indicators would always exist and would roll up to the Enclosure + Fault indicator, and additionally, the Rack and Row Identify indicators would + have an additional Fault indicator (not shown) and the Fault indicators at the enclosure level would roll up to those.
- +
- +
Service Indicator Requirements Service indicators are required on all platforms. - + - R1-R1--1. All platforms must implement either the @@ -1199,10 +1199,10 @@ enclosures (for example, I/O expansion drawers)) within the platform must be operating in the same mode. - + - R1-R1--2. Indicators defined by this architecture must @@ -1210,106 +1210,106 @@ architecture, and only with the specific states defined by this architecture. - + - R1-R1--3. - All platforms must provide the + All platforms must provide the “ibm,service-indicator-mode” property in the Open Firmware Device Tree root node. - + - +
Service Indicator General Requirements This section details requirements of indicators that are not specifically LoPAR indicator type 9006 or 9007 related. These are true even if the platform does not present any 9007 indicators to the OS. This includes requirements for platform actions like roll-up. For 9006 and - 9007 specific requirements, see + 9007 specific requirements, see . - Requirements which are prefaced by - “For Lightpath Mode platforms:” + Requirements which are prefaced by + “For Lightpath Mode platforms:” only apply to - Lightpath Mode platforms. Requirements which are prefaced by + Lightpath Mode platforms. Requirements which are prefaced by “For Guiding Light Mode platforms:” only apply to Guiding Light Mode platforms. Requirements that are prefaced by - neither, apply to both Lightpath Mode and Guiding Light Mode platforms. + neither, apply to both Lightpath Mode and Guiding Light Mode platforms. Components which are designed to work in both Lightpath Mode and Guiding Light Mode platforms, need to be able to comply with both Lightpath Mode and Guiding Light Mode sets of requirements, as well as the requirements that apply to all. - +
Fault Detection and Problem Determination Requirements There are two general classifications of problems which are indicated by Service Indicators: - - + + An indication for FRUs that have failed and need to be replaced - + An indication of other system problems that may be causing performance degradation or which might cause failures in the future, for example: - - + + A FRU that is predicted to fail (may be treated as a failing FRU by some implementations) - + An over temperature conditions - + A loss of redundancy that is not caused directly by a FRU failure (for example, greater than 100% of the power of the base power being used) - + A configuration problem such as a missing resource, resource plugged into the wrong slot, or invalid configuration - + - - + + The general model for use of the Error Log Previously called the System Information (Attention) indicator. and Enclosure Fault indicators is to indicate problems as follows: - - + + Activation of either the Error Log or Enclosure Fault indicators is accompanied by a log entry in an error log that can be queried by the user - + Activation of the Error Log indicator is used when the user needs to perform some procedure, or acknowledge some condition, prior to taking corrective action - - + + For most types of problems, this requires the user to look into the error log at the start of the procedure - + In some cases (generally for more common or more urgent problems), additional indicators may be provided by a system and @@ -1318,169 +1318,169 @@ be the same indicators as defined by this architecture, except as allowed by this architecture) - + The procedure performed by the user may include items like: - - + + Activation of FRU Identify indicators (for example, as in Guiding Light Mode systems) - + Removal and re-connection of cables, reseating of cards, etc. - + - + - + Activation of an Enclosure Fault (Lightpath Mode systems) is only allowed in the following cases: - + As an indication of the roll-up of a FRU Fault indicator - + In conjunction with a system error that prevents a FRU Fault indicator from being activated (this requires some other indication of the global failure problem, for example, an error code on an op panel) - + - - + + The following requirements define the actions to be taken by a system on the detection of a fault. - + - R1-R1--1. The detector of a fault condition must do the following: - - + + If the a fault occurs which cannot be isolated appropriately without the user performing some procedure, then activate the Error Log indicator. - + If a fault occurs which can be isolated to a single FRU and if there exists a Fault indicator for the FRU, then activate that FRU Fault indicator, otherwise activate the Error Log indicator. - + If a fault occurs which cannot be isolated to a single FRU and if there exists a Fault indicator for the most likely FRU in the FRU list, then activate that FRU Fault indicator, otherwise activate the Error Log indicator. - + If a fault occurs which is isolated to a group of FRUs (called a FRU group) and if there exists a Fault indicator for each of the FRUs, then activate all the FRU Fault indicators, otherwise activate the Error Log indicator. - - - See also, + + + See also, . - - + + - R1-R1--2. (Requirement Number Reserved For Compatibility) - - + + - R1-R1--3. Service Indicators (Error Log, Fault, and Identify) must be activated appropriately to guide a user to or through a service action or procedure. - - + + - R1-R1--4. Service Indicators (Error Log, Fault, and Identify) must be deactivated appropriately, as follows: - - + + A Service Indicator activated by an entity must be automatically deactivated by that entity when that entity can determine that the activation is no longer necessary, or - + A Service Indicator must be automatically deactivated by the platform when the platform can determine that the activation is no longer necessary or may be necessary but will be redetected and therefore reactivated a reasonable time later, or - + A Service Indicator must be automatically deactivated by a service procedure which fixes the issue that caused the indicator to be automatically activated in the first place, or - + A Error Log or Identify indicator must be deactivated when a user request it to be deactivated by a system-level user interface. - + For the Lightpath UI Base Enablement, as indicated in - Requirement - and - and + . - + - - + + - R1-R1--5. For each activation of the Error Log and Enclosure Fault Indicators, one of the following must be true: - - + + If the platform is functional enough to allow it, then an associated entry must be made in an error log that can be queried by a user interface. - + In the case where the platform is not functional enough to allow logging of an error log @@ -1488,43 +1488,43 @@ associated with the indicator activation (for example, an error code on an op panel on the system). - - + + Implementation Notes: - - + + - Requirement + Requirement are intentionally written general enough so that different platform types have some latitude in - implementation of Service Indicators. However, see the state diagrams, + implementation of Service Indicators. However, see the state diagrams, , for some explicit requirements for activation and deactivation of the various Service - Indicators. Those state diagrams take precedence over Requirement + Indicators. Those state diagrams take precedence over Requirement . When the state diagrams and - Requirement + Requirement do not give explicit direction for implementation, implementers should consider compatibility with existing implementations when making decisions about activation and deactivation. - + - 2. In Requirement + 2. In Requirement , the physical indicator may not be turned off when deactivated from an OS interface (versus a system-level interface), if another entity outside of that OS also has the physical indicator activated. That is, if the physical indicator is the combination of several logical indicators. - + - - + + - R1-R1--6. The Error Log @@ -1538,74 +1538,74 @@ a service action that the customer can perform or it may require a service provider. - + - +
- +
FRU-Level and Connector Indicator Requirements The indicators specified in this section represent the lowest level indicators in the indicator roll-up hierarchy. - See also requirements in + See also requirements in . - For the Lightpath UI, see also the requirements in + For the Lightpath UI, see also the requirements in . - + - R1-R1--1. For Lightpath Mode platforms: All of the following must be true: - - + + A FRU Fault indicator must be implemented for every replaceable FRU, with the states of “off” and “on,” except - for FRUs which are excepted in Requirement + for FRUs which are excepted in Requirement . - + Clearing of the FRU Fault indicator from the Fault state must be the result of part of the repair action and must be transparent to the OS(s) and SFP (that is, the OS or SFP is not required to automatically clear a FRU Fault indicator). - + The physical indicator which implements the FRU Fault indicator must also be Identify indicator and follow the requirements for Identify indicators. - + - - + + - R1-R1--2. FRU indicators (Fault and Identify) must be visible to the user during a service action. - Implementation Note: Requirement + Implementation Note: Requirement may require, for example, that the indicator be able to be lit after power is removed from the system, requiring storage of power on the component with the indicator (for example, via a capacitor) and activation of the indicators by a push - button by the user (see Requirement + button by the user (see Requirement for requirements on this implementation). Another example would be via the use of a light pipe from the indicator to a visible place. - - + + - R1-R1--3. For Guiding Light Mode platforms: @@ -1617,41 +1617,41 @@ except that a FRU Identify indicator may be activated to the Fault state (on solid) as a result of a FRU failure if all of the following are true: - - + + The failure that is being indicated must be a failure which prevents the user from activating the said FRU Identify indicator to the Identify state. - + Clearing of the FRU Fault indicator must be the result of part of the repair action and must be transparent to the OS, SFP, and HMC. - - + + Architecture Notes: - - + + For Guiding Light Mode platforms, the only FRU-level indicators that are allowed to be visible to an OS, SFP, or HMC are the FRU Identify indicators. - + For Guiding Light Mode platforms, the only Fault indicator that is allowed to be visible to an OS, SFP, or HMC is the Error Log indicator. - + Examples of the exception of the use of FRU and enclosure - indicators in Requirement + indicators in Requirement as an indication of a fault are: when the path for controlling an Enclosure Identify indicator or FRU indicator in that enclosure is broken, or when the power supply in the @@ -1661,12 +1661,12 @@ would be returned to the Normal state as a result of the repair action that fixes the problem. - + - - + + - R1-R1--4. All platforms @@ -1680,8 +1680,8 @@ must include an Identify indicator for every FRU with the states of “off” and “blink,” except for the following classes of FRUs: - - + + If a device driver has access to some standard form of Identify/Fault indicators for @@ -1689,7 +1689,7 @@ enclosure services), then the platform does not need to provide FRU indicators for these devices. - + If a device driver has access to some standard form of Identify/Fault indicators for @@ -1697,14 +1697,14 @@ of enclosure services), then the platform does not need to provide FRU indicators for these devices. - + External enclosures other than PCI expansion enclosures, and external devices (for example, keyboard, mice, tablets) that attach via cable to IOAs, do not require FRU indicators. - + Cables that connect from IOAs to the devices defined in parts , @@ -1712,36 +1712,36 @@ of this requirement do not require FRU indicators. - + Internal cables, interposers, and other FRUs which do not contain active components do not require FRU indicators. - - + + Implementation Note: Even though an item falls into - the list of possible exceptions in Requirement + the list of possible exceptions in Requirement , the designer of such a component should verify that leaving off the FRU Identify indicator from their component will not prevent the systems in which that component is used from meeting their serviceability requirements. - - + + - R1-R1--5. All FRU-level - Identify indicators must implement the state diagram shown in + Identify indicators must implement the state diagram shown in , except that the Fault state is not required for Guiding Light Mode platforms. - - + + - R1-R1--6. All platforms @@ -1749,280 +1749,280 @@ and “blink” for every connector that is to be involved in an Identify operation. - - + + - R1-R1--7. FRU-level and connector-level indicators must be made visible to the OS(s) as follows, and must be made transparent otherwise: - - + + For Lightpath Mode platforms: FRU Fault indicators must be made visible to the OS for FRUs for which the OS image is expected to detect errors for either the entire FRU or part of the FRU. - + FRU Identify indicators must be made visible to the OS for FRUs that are fully owned by the OS image. - + Connector Identify indicators must be made visible to the OS for connectors that are fully owned by the OS image and for which a connector Identify indicator exists. - - + + Implementation Notes: - - + + - In Requirement In Requirement , for FRU Fault indicators that are shared, the FRU Fault indicator is virtualized, so that one partition cannot view the setting by another partition, which would allow a covert - storage channel (see also - and + storage channel (see also + and ). - + Ownership of a FRU or connector by the OS image is defined as being the condition of the FRU or connector being under software control by the OS, a device driver associated with the OS, or application software running on the OS. - + - - + + - R1-R1--8. An OS which activates a FRU Identify indicator must provide a method of deactivating that indicator. - - + + - R1-R1--9. (Requirement Number Reserved For Compatibility) - + - +
- +
Enclosure-Level Indicator Requirements - See also requirements in + See also requirements in . - For the Lightpath UI, see also the requirements in + For the Lightpath UI, see also the requirements in . - + - R1-R1--1. On the System Enclosure: The platform must implement an Error Log indicator and all of the following must be true: - - + + The states of “off” and “on” must be implemented and must be used for the Error Log function - + (Requirement Number Reserved For Compatibility) - + This indicator must roll-up to the rack indicator, when the rack indicator is implemented, and for blade implementations, to the Chassis Error Log indicator. - + - The indicator must implement the state diagram shown in + The indicator must implement the state diagram shown in . - + The platform must provide a mechanism to allow the user to put the Error Log indicator into the off state. - + - - + + - R1-R1--2. Except for enclosures that contain only FRUs that are exempted from FRU-level indicators as specified by - Requirement - parts - , - , and + Requirement + parts + , + , and , and which also do not have any Connector Identify indicators, the platform must implement an Enclosure Identify indicator on all enclosures, and all the following must be true: - - + + The states of “off,” “blink,” and “on” must be implemented and must be used for the Identify function. - + This indicator must roll-up to the rack indicator, when the rack indicator is implemented, and for blade implementations, to the Chassis Enclosure Identify indicator. - + - The indicator must implement the state diagrams shown in - and + The indicator must implement the state diagrams shown in + and . - + - - + + - R1-R1--3. For Lightpath Mode Platforms: All the following must be true for the Enclosure Fault indicator: - - + + The platform must implement an Enclosure Fault indicator on each enclosure in which there exists at least one FRU Fault indicator. - + These indicators must implement the states of “off,” “on,” and “blip”. - + - These indicators must implement the state diagram as shown in + These indicators must implement the state diagram as shown in . - + These indicators must not be visible to any OS image. - + The platform must provide a mechanism to allow the user to put each Enclosure Fault indicator into the blip state. - + This indicator must roll-up to the rack indicator, when the rack indicator is implemented, and for blade implementations, to the Chassis Enclosure Fault indicator. - - - + + + - Implementation Note: One way of achieving Requirement - Implementation Note: One way of achieving Requirement + is to provide a pushbutton (for example, on the secondary indicator panel). - - + + - R1-R1--4. (Requirement Number Reserved For Compatibility) - - + + - R1-R1--5. (Requirement Number Reserved For Compatibility) - - + + - R1-R1--6. Enclosure-level indicators must be made visible to the OS(s) as follows, and must be made transparent otherwise: - - + + Enclosure Identify indicators must be made visible to the OS when the OS fully owns a FRU in the enclosure. - + The Error Log indicator must be made visible to each OS image. - - + + Implementation Notes: - - + + - In Requirement + In Requirement , for indicators that are shared, the indicator is virtualized, so that one partition cannot view the setting by another partition, which would allow a covert storage - channel (see also - and + channel (see also + and ). - + Ownership of a FRU by the OS image is defined as being the condition of the FRU being under software control by the OS, a device driver associated with the OS, or application software running on the OS. - + - - + + - R1-R1--7. An OS which @@ -2030,35 +2030,35 @@ that indicator, when such an activation is not be deactivated automatically as part of the service action. - - Implementation Note: Relative to Requirement + + Implementation Note: Relative to Requirement , it is recommended that an OS that activates an Error Log indicator, provide a way to deactivate that indicator, regardless of whether that indicator would be reset as part of a service action. - - + + - R1-R1--8. An OS which activates an Enclosure Identify indicator must provide a method of deactivating that indicator. - - + + - R1-R1--9. (Requirement Number Reserved For Compatibility) - - + + - R1-R1--10. For Guiding Light Mode Platforms: If a FRU Fault @@ -2068,129 +2068,129 @@ indicator, with the same requirements as the Enclosure Fault indicator for Lightpath Mode platforms. - + - +
- +
- + Rack-Level Indicator Requirements - - See also requirements in + + See also requirements in . - + - R1-R1--1. If a platform implements a rack-level indicator then all of the following must be true: - - + + The rack indicator must be transparent to the OS, SFP, and HMC. - + The rack indicator must be Highly visible As defined by our usability groups (distance and viewing angle) with covers in place. - + For Lightpath Mode: The rack tower indicator must - implement the state diagram indicated in - , - , and + implement the state diagram indicated in + , + , and . - + For the Guiding Light Mode: The rack tower indicator - must implement the state diagram indicated in - , + must implement the state diagram indicated in + , , and if the optional Enclosure - Fault indicators are implemented, then + Fault indicators are implemented, then . - + - + - +
- +
Row-Level Indicator Requirements - + - R1-R1--1. If a system implements a row-level indicator to roll-up a row of rack-level indicators, then the following must be true for these indicators: - - + + The indicator must be transparent to the OS, SFP, and HMC. - + For Lightpath Mode: This indicator must implement the - state diagram indicated in - , - , and + state diagram indicated in + , + , and . - + For the Guiding Light Mode: This indicator must - implement the state diagram indicated in - , + implement the state diagram indicated in + , , and if the optional Enclosure - Fault indicators are implemented, then + Fault indicators are implemented, then . - + - + - +
- +
Shared Indicator (Multiple Partition System) Requirements - To avoid covert storage channels (see + To avoid covert storage channels (see ), virtual indicators are required for physical indicators which are shared between OS images. - + - R1-R1--1. If a physical indicator (Fault or Identify) is shared between more than one partition, all the following must be true: - - + + Except where there is explicit trust between the partitions, the platform must provide a separate virtual indicator to each non-trusted partition for each shared physical indicator and must control the - physical indicator appropriately, as indicated in the state diagrams in + physical indicator appropriately, as indicated in the state diagrams in . - + If software in a partition senses the state of the virtual indicator, it must take into consideration that it is seeing the virtual @@ -2198,53 +2198,53 @@ being what the partition set the indicator to, and this is not necessarily what the physical indicator is actually displaying. - + The SFP must be given access (sense and set) to the physical FRU level indicators, and the platform must clear all the corresponding virtual indicators when physical indicator is cleared by the SFP. - + The SFP must be given access (sense and set) to the physical Error Log indicator, and the platform must not clear the corresponding virtual indicators when physical indicator is cleared by the SFP. - - + + Architecture Note: - - + + - In Requirement + In Requirement , an example of “explicit trust” is where the sharing partitions are the SFP and one other partition, where the SFP is running in an OS where all the applications and drivers can be trusted to not open a covert channel to the other OS or application in that other partition. - + - In Requirement + In Requirement , it may be possible for the SFP to get direct access to the virtual indicators, but such access is beyond the scope of this architecture. - + - + - +
- +
Additional Indicator Requirements - + - R1-R1--1. A user interface which presents to a @@ -2256,32 +2256,32 @@ example, prompt the user whether they want to refresh the list of available indicators). - - + + - R1-R1--2. The color of indicators must be as follows: - - + + FRU Identify, FRU Fault, Enclosure Fault, Error Log indicators, and any roll-up indicators for Error Log (rack-level, blade system chassis-level, and row-level) must be amber. - + The Enclosure Identify indicators and any roll-up indicators for these indicators (rack-level, blade system chassis-level, and row-level) must be blue. - + - - + + - R1-R1--3. The blink rate of @@ -2293,10 +2293,10 @@ with the industry standard SHPC specification, which specifies 2 Hz with 1 Hz minimum. - - + + - R1-R1--4. The @@ -2304,20 +2304,20 @@ “remind” state must be nominally 0.5 Hz with a duty cycle of 0.2 seconds on, 1.8 seconds off. - - + + - R1-R1--5. All indicator roll-up (activate and deactivate) must be controlled entirely by the platform and must be transparent to the OS, SFP, and HMC. - - + + - R1-R1--6. Duplicate indicators that are @@ -2327,10 +2327,10 @@ enclosure) must be transparent to the OS and must be kept synchronized by the platform. - - + + - R1-R1--7. The platform must @@ -2338,10 +2338,10 @@ etc.) without any OS present, for test purposes (manufacturing, field service, etc.). - - + + - R1-R1--8. The hardware must provide the firmware a @@ -2349,10 +2349,10 @@ controls the visual state, not the actual visual state) as well as to set the state of the indicators. - - + + - R1-R1--9. The platform must @@ -2360,22 +2360,22 @@ capability to use the Identify indicator(s) remaining in the platform or affect any roll-up. - - + + - R1-R1--10. In reference to - Requirement , if a capacitor and pushbutton are used to be able to activate the indicator after removal of the part, then all the following must be true: - - + + - For Lightpath Mode platforms: Both + For Lightpath Mode platforms: Both the Identify and the Fault states must be supported, and the indicator must activate when the push button is depressed and must go off (with the remaining @@ -2383,22 +2383,22 @@ state is displayed as “blink” and Fault state as “on”). - + - For Guiding Light Mode platforms: + For Guiding Light Mode platforms: The Identify state must be supported, and the indicator must activate (“blink”) when the push button is depressed and must go off (with the remaining capacitor charge maintained) when the pushbutton is released. - + There must be a green indicator next to the pushbutton and the indicator must get turned on when the button is pressed and when there is charge in the capacitor, and must be off when the button is not pressed. - + The capacitor must have the capability to store enough charge for two hours and after that period must be able to light for 30 seconds @@ -2406,83 +2406,83 @@ any necessary group of FRUs (for example, four additional indicators if a group of four DIMM locations is to be identified simultaneously). - - + + - Implementation Note: As part of Requirement + Implementation Note: As part of Requirement , it is not necessary to roll-up any activated indicators to the next level when the button is pressed. - - + + - R1-R1--11. All indicators which are under standby power must work the way they do when full power is applied to the system, including all of the following: - - + + The indicators must continue to display the last state displayed when the system power went to standby-only power, unless the state is changed during the standby state by the user or by a service action. - + The changing of the state to the Identify state and then back to the previous state by the user must be supported, when that functionality is supported during full system power. - - + + Implementation Note: Internal to the platform firmware, it will most likely be required to have a common control point for all service indicators in order to meet the requirements and meet the necessary state information - - + + - R1-R1--12. Any secondary (intermediate) level - roll-up indicator (see + roll-up indicator (see ) must behave as follows: - - + + Be blinking, if any Identify indicator that it represents is blinking - + Be on solid if any Fault indicator that it represents is on and no Identify indicator that it represents is blinking - + Be off if all indicators that it represents are off - + - - + + - R1-R1--13. The icons used for the following indicators, and any roll-up of the same, must be as follows (see the usability specifications for size, color, and placement): - - + + For the Error Log indicator: @@ -2498,7 +2498,7 @@ - + For the Enclosure Fault indicator: @@ -2514,7 +2514,7 @@ - + For the Enclosure Identify indicator: @@ -2530,13 +2530,13 @@ - + - + - +
- +
Blade Systems Chassis-level Indicator Requirements @@ -2546,52 +2546,52 @@ that the Enclosure Identify indicators are required to be able to be turned on/off by a user interface, unlike the rack and row level indicators. - For the Lightpath UI, see also the requirements in + For the Lightpath UI, see also the requirements in . - + - R1-R1--1. The blade chassis must implement an amber Error Log indicator, with the state diagram - indicated in + indicated in . - - + + - R1-R1--2. The blade chassis must implement an amber Enclosure Fault indicator, with the state diagram - indicated in + indicated in . - - + + - R1-R1--3. The blade chassis must implement an blue Enclosure Identify indicator, with the state - diagram indicated in + diagram indicated in . - + - +
- +
Service Indicator State Diagrams The following state diagrams show the transitions and states for the service indicators in the system. - Implementation Note: Activation of an + Implementation Note: Activation of an indicator by a roll-up operation from a lower level indicator will prevent a user from turning off such an indicator from a user interface without turning off @@ -2604,9 +2604,9 @@ turning off such an indicator is not possible, when a roll-up to that indicator is active (for example, by graying out the option on the user interface). - +
- FRU or Connector Fault/Identify + <title>FRU or Connector Fault/Identify Indicator State Diagram @@ -2619,79 +2619,79 @@
- + Notes: - + - Not being available means the failure that is being + Not being available means the failure that is being indicated must be a failure which prevents the user from activating the Identify for the FRU. - + - Transition to Fault state may occur if a failure - occurs which would prevent the activation of the indicator - into one of the Identify states. Not all FRU Fault indicators + Transition to Fault state may occur if a failure + occurs which would prevent the activation of the indicator + into one of the Identify states. Not all FRU Fault indicators in an enclosure get activated like this simultaneously; - only those that are directly involved with the fault + only those that are directly involved with the fault (for example, like the FRU Fault indicator associated with the indicator controller hardware) - + - OS is not expected to change an - indicator from Fault to Normal, but is permitted to do so - (providing that it has access to the indicator because it + OS is not expected to change an + indicator from Fault to Normal, but is permitted to do so + (providing that it has access to the indicator because it owns the resource). - + - Transition from Fault to the Identify - or Normal states by the OS may not be possible if a hardware - fault causes a failure which prevents access to the + Transition from Fault to the Identify + or Normal states by the OS may not be possible if a hardware + fault causes a failure which prevents access to the indicator. - + - Format on the above diagram of “xxxx,y” means a - call to the set-indicator or + Format on the above diagram of “xxxx,y” means a + call to the set-indicator or ibm,set-dynamic-indicator - RTAS call with an indicator token of “xxxx” and a state + RTAS call with an indicator token of “xxxx” and a state value of “y” (only the token applicable for the specific indicator causes a state transition). - + The 9002 Identify and Action are the same state. - + - 9006 FRU-level indicators only + 9006 FRU-level indicators only provided in Lightpath Mode platforms. - + - Fault indicators may be virtualized, - with several OS images and firmware given access to a virtual - FRU Fault indicator which controls the same physical + Fault indicators may be virtualized, + with several OS images and firmware given access to a virtual + FRU Fault indicator which controls the same physical Fault/Identify indicator. These get combined as shown in the state - diagram, above; all virtual Fault indicators basically get + diagram, above; all virtual Fault indicators basically get ORed together. - + - This indicator may be forced to the Normal (off) + This indicator may be forced to the Normal (off) state under certain circumstances (for example, see Requirement ). - + - For the Lightpath UI, when implemented, - other transition conditions are possible. See + For the Lightpath UI, when implemented, + other transition conditions are possible. See for requirements. - +
@@ -2710,37 +2710,37 @@
Notes: - + - Format on the above diagram of “xxxx,y” means - a call to the set-indicator or + Format on the above diagram of “xxxx,y” means + a call to the set-indicator or ibm,set-dynamic-indicator - RTAS call with an indicator token of “xxxx” and a state + RTAS call with an indicator token of “xxxx” and a state value of “y” (only the token applicable for the specific indicator causes a state transition). - + - This indicator may be forced to the Normal - (off) state under certain circumstances (for example, see + This indicator may be forced to the Normal + (off) state under certain circumstances (for example, see Requirement ). - + - See Requirement - See Requirement + . - + - For the Lightpath UI, when implemented, other transition conditions - are possible. See + For the Lightpath UI, when implemented, other transition conditions + are possible. See for requirements. - +
@@ -2759,33 +2759,33 @@
Notes: - + - This indicator may be forced to the Normal (off) - state under certain circumstances (for example, see Requirement - ). + This indicator may be forced to the Normal (off) + state under certain circumstances (for example, see Requirement + ). This indicator is off at the end of POST. - The states in this diagram overlay the corresponding - states in - . + The states in this diagram overlay the corresponding + states in + . This figure represents the POST states and the after-POST states. - The use of the Optional Identify state to indicate boot + The use of the Optional Identify state to indicate boot identify is only to be used for boot servers - for scalable system nodes or blades of a blade system - (for example, NUMA system nodes), and not for stand-alone + for scalable system nodes or blades of a blade system + (for example, NUMA system nodes), and not for stand-alone systems or blades - + - +
Enclosure Identify Indicator State Diagram @@ -2802,58 +2802,58 @@
Notes: - + - This indicator may be activated to the on state + This indicator may be activated to the on state by any OS which is given access to the indicator per Requirements. - For indicators that are shared by multiple OS instances, this indicator - is virtualized (see + For indicators that are shared by multiple OS instances, this indicator + is virtualized (see - and - ). - LoPAR compliant OSs are only given the capability to activate the - Enclosure ID to the on state, not to the blink state. The blink state + and + ). + LoPAR compliant OSs are only given the capability to activate the + Enclosure ID to the on state, not to the blink state. The blink state may be activated through an external platform management interface by a user request through that interface to blink the physical Enclosure ID. - This indicator may be forced to the off state under - certain circumstances (for example, see Requirement - ). + This indicator may be forced to the off state under + certain circumstances (for example, see Requirement + ). This indicator is off at the end of POST. - A user is not allowed to deactivate the Enclosure ID if + A user is not allowed to deactivate the Enclosure ID if there are still FRU IDs still active. - A user request through a privileged user interface (for example, + A user request through a privileged user interface (for example, via an SFP) to set the physical Enclosure ID to off, - forces any virtual Enclosure ID indicators that are active (on or + forces any virtual Enclosure ID indicators that are active (on or blink) to their off state, but this does not override any FRU ID roll-ups (see Note ). - For Scalable (NUMA) systems, the states in this diagram - overlay the corresponding states in - . - This figure represents the after-POST states and - . + For Scalable (NUMA) systems, the states in this diagram + overlay the corresponding states in + . + This figure represents the after-POST states and + . the POST states. - A virtual Enclosure ID can be activated or turned off by the + A virtual Enclosure ID can be activated or turned off by the 9007 indicator token for the target Enclosure ID. - + - +
Enclosure Fault Indicator State Diagram @@ -2870,37 +2870,37 @@
Notes: - + - There is no direct activation or deactivation of + There is no direct activation or deactivation of this indicator by any OS. - See Requirement + See Requirement and the Implementation Note below that requirement. - This indicator may be forced to the Normal (off) - state under certain circumstances (for example, see Requirement + This indicator may be forced to the Normal (off) + state under certain circumstances (for example, see Requirement ). - Activation of an Enclosure Fault indicator without + Activation of an Enclosure Fault indicator without activating a FRU Fault indicator within the - enclosure is to be used only in exceptional cases where + enclosure is to be used only in exceptional cases where the FRU Fault cannot be activated. In - such cases the system is required to also provide + such cases the system is required to also provide further direction to the user on how to resolve - the fault (for example, by providing an error code on an + the fault (for example, by providing an error code on an op panel on the system). - + - +
For Blade Systems: Chassis-level Error Log Indicator State Diagram @@ -2947,34 +2947,34 @@
Notes: - + - This indicator may be forced to the Normal (off) state + This indicator may be forced to the Normal (off) state under certain circumstances (for example, see Requirement ). - A user is not allowed to deactivate the chassis Enclosure + A user is not allowed to deactivate the chassis Enclosure ID if there are still FRU Identify or Blade Enclosure - Identify indicators still active (see state transition qualifiers + Identify indicators still active (see state transition qualifiers in the above diagram). - A user request to set the Chassis Enclosure ID to the + A user request to set the Chassis Enclosure ID to the Identify (blink) state temporarily overrides roll-up operations (roll-up operations set the indicator to the on state). - A user request to change state of the Chassis Enclosure + A user request to change state of the Chassis Enclosure ID cancels any previous user request against the same indicator, replacing the user requested state with the new state. - + - +
Rack-level Error Log Indicator State Diagram @@ -3065,35 +3065,35 @@
- Notes: A blinking Enclosure ID - is assumed to be “active” for purposes of the Row Enclosure ID indicator + Notes: A blinking Enclosure ID + is assumed to be “active” for purposes of the Row Enclosure ID indicator state.
- +
Requirements for 9002, 9006, and 9007 Indicators - See + See for service indicator requirements that are not 9006 and 9007 specific. - R1-R1--1. When the platform presents a 9006 indicator to an OS, the following must be true: - - + + The platform must set the location code of the Error Log (9006) indicator and sensor to be the location code of the system and this indicator or sensor must be the first one in the list of 9006 indicators or sensors. - + For Lightpath Mode platforms: The platform must set @@ -3101,88 +3101,88 @@ location code of the component to which that indicator or sensor is associated. - + For every 9006 indicator, there must be a corresponding 9006 sensor which has the same index as the corresponding indicator. - + - + - R1-R1--2. When 9007 - indicators are to be provided to an OS, the platform must implement the + indicators are to be provided to an OS, the platform must implement the ibm,get-indices RTAS call and must present that call in the device tree for the OS, and the OS needing access to the 9007 - indicators and sensors must use the + indicators and sensors must use the ibm,get-indices call to get the indices of the 9007 indicators and sensors available to the partition at the time of the call. Software Implementation Notes: - - + + - Relative to Requirement + Relative to Requirement , due to Dynamic Reconfiguration, the indicators available at any point in time might be - different than on a previous call to + different than on a previous call to ibm,get-indices. - + 9007 indicators may need to be provided to the OS in the order in which they are best displayed to the user, because the OS or the UI may not reorder them (for example, sort them) before presenting them to the user. This is true regardless of the method of presentation to the OS - (OF device tree or + (OF device tree or ibm,get-indices RTAS call). Relative to presentation - order, see also Requirement - - + - + - R1-R1--3. If a platform provides any 9007 indicators to the OS, then the following must be true: - - + + The platform must set the location code of each Identify (9007) indicator and sensor (Enclosure, FRU, or connector) to be the location code of the enclosure, FRU, or connector to which that indicator is associated. - + The System Enclosure Identify (9007) indicator must be the first indicator in the list of 9007 indicators. - + For every 9007 indicator, there must be a corresponding 9007 sensor which has the same index as the corresponding indicator. - + - + - R1-R1--4. A DR indicator (9002) must only be @@ -3190,10 +3190,10 @@ going to control the physical add, remove, and replace operations on the FRU which is pointed to by that particular DR indicator. - + - R1-R1--5. If a PCI Hot Plug slot implements a single @@ -3202,26 +3202,26 @@ indicator must be presented to a LoPAR compliant OS as both a 9002 and 9007 indicator. - + - R1-R1--6. - All platforms must provide the - “ibm,fault-behavior” and + All platforms must provide the + “ibm,fault-behavior” and “ibm,fru-9006-deactivate” properties in - the + the root node of the OF device tree, both with a value of 1. - + - +
- +
- + Lightpath User Interface (UI) Requirements The base Lightpath architecture does not provide a User Interface (UI), per se, when one considers a UI as being an interactive entity; @@ -3230,7 +3230,7 @@ is necessary. This architecture will call this the Lightpath UI. The Lightpath UI is an interface between the Service Focal Point (SFP) and the user of the SFP, and at a minimum, provides an interface to show - hidden Fault indicators (for example, see + hidden Fault indicators (for example, see ). A slightly more sophisticated Lightpath UI -- one with a General UI (GUI) such as an LCD or general display like provided by IBM Director -- is required to @@ -3261,14 +3261,14 @@ exhibit different levels of sophistication in larger systems. The following are some (not all) system implementation examples: - + For simple systems, there may be no SFP and no Lightpath UI, which means everything needs to be resolved by Fault indicators. - For simple systems implementing Triple-S (see + For simple systems implementing Triple-S (see ), there may exist a simple SFP with a simple Lightpath UI like one or more physical push-buttons. This could be the System Error indicator with a physical button associated @@ -3281,59 +3281,59 @@ on the physical indicators. In this case, the Lightpath UI is not full-function and does not provide for enablement of the Identify indicators. In this case, the firmware driving the Lightpath UI would use - the Lightpath UI base enablement (see + the Lightpath UI base enablement (see ). For intermediate systems, the Lightpath UI could be an LCD panel. In this case, the firmware driving the Lightpath UI would use the - Lightpath UI base enablement (see + Lightpath UI base enablement (see ). The Triple-S UI is also - possible (see + possible (see ). For larger systems, the Lightpath UI could be part of a more sophisticated interface, like IBM Director. This more sophisticated - interface would use the Lightpath UI base enablement (see + interface would use the Lightpath UI base enablement (see ). The Triple-S UI is also - possible (see + possible (see ). - - + +
Lightpath UI Base Enablement Requirements This section defines the base enablement requirements for all Lightpath UI implementations. The Triple-S UI is one example of such a Lightpath UI that uses the Lightpath UI Base Enablement. Other Lightpath UIs are possible, and are not limited by this architecture. - + - R1-R1--1. For the Lightpath UI Base Enablement: The platform must do all of the following: - - + + Implement Lightpath Mode, as defined by this architecture, lighting FRU Fault indicators or Error Log indicator associated with a fault. Lightpath Mode includes the implementation of Identify indicators. - + If the SFP is separate from the platform, then report to the SFP that the platform implements the Lightpath UI Base Enablement (explicitly or implicitly). (see implementation note, below) - + Whenever possible, report all fault conditions which activate a FRU Fault @@ -3343,7 +3343,7 @@ note, below, for the only exception cases allowed to this requirement. - + Accept commands from the Service Focal Point (SFP) to put each indicator (FRU, Enclosure, @@ -3353,94 +3353,94 @@ to which the indicator is already activated. See the implementation note, below, for the only exception cases allowed to this requirement. - + Prevent multiple reports of same error, whenever possible. (see implementation note, below) - - + + Implementation Notes: - - + + - Requirement - Requirement + allows a SFP to manage multiple platforms that implement different Service Indicator modes. Note that this requirement can be implemented implicitly from other information reported to the SFP (for example, machine type/model). - + - In Requirement - and - In Requirement + and + , acceptable reasons for not being able to report errors to the SFP or have the SFP control the LEDs may include: - - + + Loss of communications between the component and the SFP. - + A fault indicator that is entirely controlled by an OS, hardware, or code, or an entity which is not in communications with the platform firmware or the SFP. - + - + - Requirement - Requirement + prevents continual “blinking” of Fault indicator and the flooding of the SFP’s event or error log. - + - - + + - R1-R1--2. For the Lightpath UI Base Enablement: The Service Focal Point (SFP) must exist and must do all of the following: - - + + Receive and log fault conditions reported by the platform. (see implementation note, below) - + Turn off each Fault indicator or Error Log indicator associated with a fault condition, as soon as possible after the fault is reported, except as required to - remain on by user request user request (for example, see Requirement + remain on by user request user request (for example, see Requirement ). - + Accept direction from a user to show any faults on the Fault and - Error Log indicators (for example, see Requirement + Error Log indicators (for example, see Requirement ). - + If the SFP contains a GUI (for example, an LCD display or a display like provided by @@ -3451,17 +3451,17 @@ (blink), along with the normal FRU roll-up defined by the base Lightpath Mode. - - + + Implementation Notes: - - + + - Relative to Requirements - Relative to Requirements + , a SFP may (but is not required to) do additional failure analysis, or may apply policy rules, on the failure(s) reported, and by doing so may change or re-prioritize @@ -3471,7 +3471,7 @@ indicators be reactivated, a different set may be activated than those that were originally activated. - + In simpler systems, it is expected that there may only be one push-button implemented, and that would be associated with the highest @@ -3481,76 +3481,76 @@ example, a SFP that manages multiple systems may (at least) implement one button per system. - + - + - +
- +
- + See/Select/Service (Triple-S) User Interface Requirements The Triple-S UI architecture is built on top of the Lightpath UI Base Enablement architecture, which is in turn built on top of the Lightpath architecture. The Triple-S architecture is basically defined as follows (see Requirements for specifics): - - + + Do not display Fault or Error Log on the physical indicators until user pushes a button or series of buttons. - - + + Except that the highest level roll-up for the Enclosure Fault indicators and Error Log indicators will be activated if a lower level one of the same type was activated. - + - + After seeing the highest level roll-up for Enclosure Fault or Error Log being on, the user pushes one or more buttons (logical or - physical) associated with those, and then the user + physical) associated with those, and then the user Sees the Faults available for servicing. - + - The user + The user Selects the item they want to service, by observing the FRU Faults and selecting they want to then Service. - - + + - The Selects part of Triple-S may also involve + The Selects part of Triple-S may also involve activation of the FRU Identify indicator from the Lightpath UI. - + - + The user completes the Service action on that component which was selected. - - - + + + - R1-R1--1. For the Triple-S UI: The Lightpath UI Base Enablement - requirements must be met, as defined in + requirements must be met, as defined in . - - + + - R1-R1--2. For the Triple-S UI: The platform must provide one or @@ -3558,13 +3558,13 @@ with a set of Fault indicators or Error Log indicators which is (are) to be used by the user to display (“show”) or not display (“hide”) fault conditions on those group of indicators, as - defined by Requirement + defined by Requirement . - - + + - R1-R1--3. For the Triple-S UI: @@ -3585,27 +3585,27 @@ button is press again or until the platform determines they are no longer needed to be on. (see implementation note, below). - - + + - R1-R1--4. For the Triple-S UI: For more complex systems, and as determined by the RAS requirements for those systems, the SFP must implement a GUI (for example, an LCD or IBM Director display) and provide the capability to activate the Identify indicators, as defined in - Requirement . - + Implementation Notes: - - + + - Relative to Requirement + Relative to Requirement , a SFP may (but is not required to) do additional failure analysis, or may apply policy rules, on the failure(s) reported, and by doing so may change or re-prioritize @@ -3615,9 +3615,9 @@ indicators be reactivated, a different set may be activated than those that were originally activated. - + - Relative to Requirement + Relative to Requirement , the set of indicators associated with a given push-button will normally be hierarchical, based on the FRU Fault or Error Log roll-up path. For example, if a push-button @@ -3633,16 +3633,16 @@ different than those activated by the entity detecting the error originally, and (3) the Identify function can be used. - + - + - +
- +
- +
Green Indicator Requirements This chapter defines the platform requirements for green @@ -3655,29 +3655,29 @@ amber indicators. There are several exceptions to having all the green indicator requirements in this chapter: - - + + The green indicator associated with a capacitor and pushbutton - implementation is specified in Requirement .). The capability to light all green indicators, as well as the amber - and blue indicators, for test purposes, is specified in Requirement + and blue indicators, for test purposes, is specified in Requirement . Unless indicated otherwise in this chapter, the blink rate for - green indicators, when they blink, is specified in Requirement + green indicators, when they blink, is specified in Requirement . - - - + + +
Green Indicator Uses and General Requirements Green indicators generally are not used for indicating a fault @@ -3685,7 +3685,7 @@ - R1-R1--1. A green indicator must not be used in @@ -3693,26 +3693,26 @@ Fault/Identify indicator is not possible, and in this exceptional case, the green must be off or blinking to indicate the error condition. - Implementation Note: Examples where a + Implementation Note: Examples where a green indicator might be used instead of an amber Fault/Identify indicator are: - - + + In a power supply to indicate lack of AC power (green off). - + In the case where there is insufficient power to power the component (green blinking). - + - + - R1-R1--2. There must exist a green power indicator @@ -3720,30 +3720,30 @@ (“hot plug” operation), unless that FRU does not require the removal of power to remove or insert that FRU. - + - +
- +
Green Indicator States This section attempts to capture the state requirements for all usages of green indicators. If a state or usage is not specified, then the user needs to get with the Architecture team for this architecture in order to add or replace any state or usage of that state. - +
Power Supply Green Indicators - + - R1-R1--1. For power supply indicators, the - platform must implement the states defined in + platform must implement the states defined in for each green indicator, and - must use those states only for the usages stated in + must use those states only for the usages stated in .   @@ -3809,23 +3809,23 @@
- + - +
- +
System Power Green Indicators - + - R1-R1--1. For system power indicators, the - platform must implement the states defined in + platform must implement the states defined in for each green indicator, and - must use those states only for the usages stated in + must use those states only for the usages stated in .   @@ -3912,23 +3912,23 @@
- + - +
- +
HDD Green Indicators - + - R1-R1--1. For Hard Disk Drives (HDD) the platform - must implement the states defined in + must implement the states defined in for each green indicator, and - must use those states only for the usages stated in + must use those states only for the usages stated in .   @@ -3991,32 +3991,32 @@
- + - +
- +
Other Component/FRU Green Indicators This section attempts to capture the state requirements for usages of green indicators that are not specifically called out as special cases - elsewhere in + elsewhere in . To reiterate what was specified, above: if a state or usage is not specified, then the user needs to get with the Architecture team for this architecture in order to add or replace any state or usage of that state. - + - R1-R1--1. For FRUs or components other than - specific ones specified elsewhere in + specific ones specified elsewhere in , which require power - indicators, the platform must implement the states defined in + indicators, the platform must implement the states defined in for each green indicator, and - must use those states only for the usages stated in + must use those states only for the usages stated in .   @@ -4085,23 +4085,23 @@
- + - +
- +
Communication Link Green Indicators - + - R1-R1--1. For communication links, the platform - must implement the states defined in + must implement the states defined in for each green indicator, and - must use those states only for the usages stated in + must use those states only for the usages stated in .   @@ -4157,12 +4157,12 @@
- + - +
- + diff --git a/Platform/ch_smp.xml b/LoPAR/ch_smp.xml similarity index 100% rename from Platform/ch_smp.xml rename to LoPAR/ch_smp.xml diff --git a/Platform/ch_system_reqs.xml b/LoPAR/ch_system_reqs.xml similarity index 100% rename from Platform/ch_system_reqs.xml rename to LoPAR/ch_system_reqs.xml diff --git a/Virtualization/ch_virtual_io.xml b/LoPAR/ch_virtual_io.xml similarity index 100% rename from Virtualization/ch_virtual_io.xml rename to LoPAR/ch_virtual_io.xml diff --git a/Platform/figures/PAPR-10.gif b/LoPAR/figures/PAPR-10.gif similarity index 100% rename from Platform/figures/PAPR-10.gif rename to LoPAR/figures/PAPR-10.gif diff --git a/Platform/figures/PAPR-11.gif b/LoPAR/figures/PAPR-11.gif similarity index 100% rename from Platform/figures/PAPR-11.gif rename to LoPAR/figures/PAPR-11.gif diff --git a/Platform/figures/PAPR-12.gif b/LoPAR/figures/PAPR-12.gif similarity index 100% rename from Platform/figures/PAPR-12.gif rename to LoPAR/figures/PAPR-12.gif diff --git a/Platform/figures/PAPR-14.gif b/LoPAR/figures/PAPR-14.gif similarity index 100% rename from Platform/figures/PAPR-14.gif rename to LoPAR/figures/PAPR-14.gif diff --git a/Platform/figures/PAPR-15.gif b/LoPAR/figures/PAPR-15.gif similarity index 100% rename from Platform/figures/PAPR-15.gif rename to LoPAR/figures/PAPR-15.gif diff --git a/Virtualization/figures/PAPR-18.gif b/LoPAR/figures/PAPR-18.gif similarity index 100% rename from Virtualization/figures/PAPR-18.gif rename to LoPAR/figures/PAPR-18.gif diff --git a/Virtualization/figures/PAPR-19.gif b/LoPAR/figures/PAPR-19.gif similarity index 100% rename from Virtualization/figures/PAPR-19.gif rename to LoPAR/figures/PAPR-19.gif diff --git a/Virtualization/figures/PAPR-20.gif b/LoPAR/figures/PAPR-20.gif similarity index 100% rename from Virtualization/figures/PAPR-20.gif rename to LoPAR/figures/PAPR-20.gif diff --git a/Virtualization/figures/PAPR-22.gif b/LoPAR/figures/PAPR-22.gif similarity index 100% rename from Virtualization/figures/PAPR-22.gif rename to LoPAR/figures/PAPR-22.gif diff --git a/Virtualization/figures/PAPR-23.gif b/LoPAR/figures/PAPR-23.gif similarity index 100% rename from Virtualization/figures/PAPR-23.gif rename to LoPAR/figures/PAPR-23.gif diff --git a/Virtualization/figures/PAPR-24.gif b/LoPAR/figures/PAPR-24.gif similarity index 100% rename from Virtualization/figures/PAPR-24.gif rename to LoPAR/figures/PAPR-24.gif diff --git a/Virtualization/figures/PAPR-25.gif b/LoPAR/figures/PAPR-25.gif similarity index 100% rename from Virtualization/figures/PAPR-25.gif rename to LoPAR/figures/PAPR-25.gif diff --git a/Virtualization/figures/PAPR-26.gif b/LoPAR/figures/PAPR-26.gif similarity index 100% rename from Virtualization/figures/PAPR-26.gif rename to LoPAR/figures/PAPR-26.gif diff --git a/Virtualization/figures/PAPR-27.gif b/LoPAR/figures/PAPR-27.gif similarity index 100% rename from Virtualization/figures/PAPR-27.gif rename to LoPAR/figures/PAPR-27.gif diff --git a/Virtualization/figures/PAPR-28.gif b/LoPAR/figures/PAPR-28.gif similarity index 100% rename from Virtualization/figures/PAPR-28.gif rename to LoPAR/figures/PAPR-28.gif diff --git a/Virtualization/figures/PAPR-29.gif b/LoPAR/figures/PAPR-29.gif similarity index 100% rename from Virtualization/figures/PAPR-29.gif rename to LoPAR/figures/PAPR-29.gif diff --git a/Virtualization/figures/PAPR-29_t0_31.gif b/LoPAR/figures/PAPR-29_t0_31.gif similarity index 100% rename from Virtualization/figures/PAPR-29_t0_31.gif rename to LoPAR/figures/PAPR-29_t0_31.gif diff --git a/Platform/figures/PAPR-3.gif b/LoPAR/figures/PAPR-3.gif similarity index 100% rename from Platform/figures/PAPR-3.gif rename to LoPAR/figures/PAPR-3.gif diff --git a/Virtualization/figures/PAPR-30.gif b/LoPAR/figures/PAPR-30.gif similarity index 100% rename from Virtualization/figures/PAPR-30.gif rename to LoPAR/figures/PAPR-30.gif diff --git a/Virtualization/figures/PAPR-31.gif b/LoPAR/figures/PAPR-31.gif similarity index 100% rename from Virtualization/figures/PAPR-31.gif rename to LoPAR/figures/PAPR-31.gif diff --git a/Platform/figures/PAPR-32.gif b/LoPAR/figures/PAPR-32.gif similarity index 100% rename from Platform/figures/PAPR-32.gif rename to LoPAR/figures/PAPR-32.gif diff --git a/Virtualization/figures/PAPR-33.gif b/LoPAR/figures/PAPR-33.gif similarity index 100% rename from Virtualization/figures/PAPR-33.gif rename to LoPAR/figures/PAPR-33.gif diff --git a/Error Handling/figures/PAPR-34.gif b/LoPAR/figures/PAPR-34.gif similarity index 100% rename from Error Handling/figures/PAPR-34.gif rename to LoPAR/figures/PAPR-34.gif diff --git a/Error Handling/figures/PAPR-36.gif b/LoPAR/figures/PAPR-36.gif similarity index 100% rename from Error Handling/figures/PAPR-36.gif rename to LoPAR/figures/PAPR-36.gif diff --git a/Error Handling/figures/PAPR-37.gif b/LoPAR/figures/PAPR-37.gif similarity index 100% rename from Error Handling/figures/PAPR-37.gif rename to LoPAR/figures/PAPR-37.gif diff --git a/Error Handling/figures/PAPR-38.gif b/LoPAR/figures/PAPR-38.gif similarity index 100% rename from Error Handling/figures/PAPR-38.gif rename to LoPAR/figures/PAPR-38.gif diff --git a/Error Handling/figures/PAPR-39.gif b/LoPAR/figures/PAPR-39.gif similarity index 100% rename from Error Handling/figures/PAPR-39.gif rename to LoPAR/figures/PAPR-39.gif diff --git a/Platform/figures/PAPR-4.gif b/LoPAR/figures/PAPR-4.gif similarity index 100% rename from Platform/figures/PAPR-4.gif rename to LoPAR/figures/PAPR-4.gif diff --git a/Error Handling/figures/PAPR-40.gif b/LoPAR/figures/PAPR-40.gif similarity index 100% rename from Error Handling/figures/PAPR-40.gif rename to LoPAR/figures/PAPR-40.gif diff --git a/Error Handling/figures/PAPR-41.gif b/LoPAR/figures/PAPR-41.gif similarity index 100% rename from Error Handling/figures/PAPR-41.gif rename to LoPAR/figures/PAPR-41.gif diff --git a/Error Handling/figures/PAPR-42.gif b/LoPAR/figures/PAPR-42.gif similarity index 100% rename from Error Handling/figures/PAPR-42.gif rename to LoPAR/figures/PAPR-42.gif diff --git a/Error Handling/figures/PAPR-43.gif b/LoPAR/figures/PAPR-43.gif similarity index 100% rename from Error Handling/figures/PAPR-43.gif rename to LoPAR/figures/PAPR-43.gif diff --git a/Error Handling/figures/PAPR-44.gif b/LoPAR/figures/PAPR-44.gif similarity index 100% rename from Error Handling/figures/PAPR-44.gif rename to LoPAR/figures/PAPR-44.gif diff --git a/Error Handling/figures/PAPR-45.gif b/LoPAR/figures/PAPR-45.gif similarity index 100% rename from Error Handling/figures/PAPR-45.gif rename to LoPAR/figures/PAPR-45.gif diff --git a/Error Handling/figures/PAPR-46.gif b/LoPAR/figures/PAPR-46.gif similarity index 100% rename from Error Handling/figures/PAPR-46.gif rename to LoPAR/figures/PAPR-46.gif diff --git a/Error Handling/figures/PAPR-47.gif b/LoPAR/figures/PAPR-47.gif similarity index 100% rename from Error Handling/figures/PAPR-47.gif rename to LoPAR/figures/PAPR-47.gif diff --git a/Error Handling/figures/PAPR-48.gif b/LoPAR/figures/PAPR-48.gif similarity index 100% rename from Error Handling/figures/PAPR-48.gif rename to LoPAR/figures/PAPR-48.gif diff --git a/Error Handling/figures/PAPR-49.gif b/LoPAR/figures/PAPR-49.gif similarity index 100% rename from Error Handling/figures/PAPR-49.gif rename to LoPAR/figures/PAPR-49.gif diff --git a/Error Handling/figures/PAPR-50.gif b/LoPAR/figures/PAPR-50.gif similarity index 100% rename from Error Handling/figures/PAPR-50.gif rename to LoPAR/figures/PAPR-50.gif diff --git a/Error Handling/figures/PAPR-51.gif b/LoPAR/figures/PAPR-51.gif similarity index 100% rename from Error Handling/figures/PAPR-51.gif rename to LoPAR/figures/PAPR-51.gif diff --git a/Error Handling/figures/PAPR-52.gif b/LoPAR/figures/PAPR-52.gif similarity index 100% rename from Error Handling/figures/PAPR-52.gif rename to LoPAR/figures/PAPR-52.gif diff --git a/Error Handling/figures/PAPR-53.gif b/LoPAR/figures/PAPR-53.gif similarity index 100% rename from Error Handling/figures/PAPR-53.gif rename to LoPAR/figures/PAPR-53.gif diff --git a/Error Handling/figures/PAPR-54.gif b/LoPAR/figures/PAPR-54.gif similarity index 100% rename from Error Handling/figures/PAPR-54.gif rename to LoPAR/figures/PAPR-54.gif diff --git a/Virtualization/figures/PAPR-55.gif b/LoPAR/figures/PAPR-55.gif similarity index 100% rename from Virtualization/figures/PAPR-55.gif rename to LoPAR/figures/PAPR-55.gif diff --git a/Virtualization/figures/PAPR-58.gif b/LoPAR/figures/PAPR-58.gif similarity index 100% rename from Virtualization/figures/PAPR-58.gif rename to LoPAR/figures/PAPR-58.gif diff --git a/Virtualization/figures/PAPR-59.gif b/LoPAR/figures/PAPR-59.gif similarity index 100% rename from Virtualization/figures/PAPR-59.gif rename to LoPAR/figures/PAPR-59.gif diff --git a/Platform/figures/PAPR-6.gif b/LoPAR/figures/PAPR-6.gif similarity index 100% rename from Platform/figures/PAPR-6.gif rename to LoPAR/figures/PAPR-6.gif diff --git a/DeviceTree/figures/PAPR-60.gif b/LoPAR/figures/PAPR-60.gif similarity index 100% rename from DeviceTree/figures/PAPR-60.gif rename to LoPAR/figures/PAPR-60.gif diff --git a/DeviceTree/figures/PAPR-61.gif b/LoPAR/figures/PAPR-61.gif similarity index 100% rename from DeviceTree/figures/PAPR-61.gif rename to LoPAR/figures/PAPR-61.gif diff --git a/DeviceTree/figures/PAPR-62.gif b/LoPAR/figures/PAPR-62.gif similarity index 100% rename from DeviceTree/figures/PAPR-62.gif rename to LoPAR/figures/PAPR-62.gif diff --git a/DeviceTree/figures/PAPR-64.gif b/LoPAR/figures/PAPR-64.gif similarity index 100% rename from DeviceTree/figures/PAPR-64.gif rename to LoPAR/figures/PAPR-64.gif diff --git a/Virtualization/figures/PAPR-66.gif b/LoPAR/figures/PAPR-66.gif similarity index 100% rename from Virtualization/figures/PAPR-66.gif rename to LoPAR/figures/PAPR-66.gif diff --git a/Virtualization/figures/PAPR-68.gif b/LoPAR/figures/PAPR-68.gif similarity index 100% rename from Virtualization/figures/PAPR-68.gif rename to LoPAR/figures/PAPR-68.gif diff --git a/Platform/figures/PAPR-7.gif b/LoPAR/figures/PAPR-7.gif similarity index 100% rename from Platform/figures/PAPR-7.gif rename to LoPAR/figures/PAPR-7.gif diff --git a/Virtualization/figures/PAPR-70.gif b/LoPAR/figures/PAPR-70.gif similarity index 100% rename from Virtualization/figures/PAPR-70.gif rename to LoPAR/figures/PAPR-70.gif diff --git a/Virtualization/figures/PAPR-71.gif b/LoPAR/figures/PAPR-71.gif similarity index 100% rename from Virtualization/figures/PAPR-71.gif rename to LoPAR/figures/PAPR-71.gif diff --git a/Virtualization/figures/PAPR-72.gif b/LoPAR/figures/PAPR-72.gif similarity index 100% rename from Virtualization/figures/PAPR-72.gif rename to LoPAR/figures/PAPR-72.gif diff --git a/Error Handling/figures/PAPR-73.gif b/LoPAR/figures/PAPR-73.gif similarity index 100% rename from Error Handling/figures/PAPR-73.gif rename to LoPAR/figures/PAPR-73.gif diff --git a/Platform/figures/PAPR-8.gif b/LoPAR/figures/PAPR-8.gif similarity index 100% rename from Platform/figures/PAPR-8.gif rename to LoPAR/figures/PAPR-8.gif diff --git a/Virtualization/figures/figure_format_vasi_add_buffer_crq_elem.gif b/LoPAR/figures/figure_format_vasi_add_buffer_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_add_buffer_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_add_buffer_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif b/LoPAR/figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_add_buffer_indirect_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_close_crq_elem.gif b/LoPAR/figures/figure_format_vasi_close_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_close_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_close_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_download_crq_elem.gif b/LoPAR/figures/figure_format_vasi_download_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_download_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_download_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_exchange_cap_crq_elem.gif b/LoPAR/figures/figure_format_vasi_exchange_cap_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_exchange_cap_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_exchange_cap_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_free_buffer_crq_elem.gif b/LoPAR/figures/figure_format_vasi_free_buffer_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_free_buffer_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_free_buffer_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_message_download_crq_elem.gif b/LoPAR/figures/figure_format_vasi_message_download_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_message_download_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_message_download_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_message_upload_crq_elem.gif b/LoPAR/figures/figure_format_vasi_message_upload_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_message_upload_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_message_upload_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_open_crq_elem.gif b/LoPAR/figures/figure_format_vasi_open_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_open_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_open_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_operation_crq_elem.gif b/LoPAR/figures/figure_format_vasi_operation_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_operation_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_operation_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_progress_crq_elem.gif b/LoPAR/figures/figure_format_vasi_progress_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_progress_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_progress_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_signal_crq_elem.gif b/LoPAR/figures/figure_format_vasi_signal_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_signal_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_signal_crq_elem.gif diff --git a/Virtualization/figures/figure_format_vasi_state_crq_elem.gif b/LoPAR/figures/figure_format_vasi_state_crq_elem.gif similarity index 100% rename from Virtualization/figures/figure_format_vasi_state_crq_elem.gif rename to LoPAR/figures/figure_format_vasi_state_crq_elem.gif diff --git a/Virtualization/figures/figure_vasi_indirect_memory_buffer_format.gif b/LoPAR/figures/figure_vasi_indirect_memory_buffer_format.gif similarity index 100% rename from Virtualization/figures/figure_vasi_indirect_memory_buffer_format.gif rename to LoPAR/figures/figure_vasi_indirect_memory_buffer_format.gif diff --git a/Virtualization/figures/general_format_crq_element.gif b/LoPAR/figures/general_format_crq_element.gif similarity index 100% rename from Virtualization/figures/general_format_crq_element.gif rename to LoPAR/figures/general_format_crq_element.gif diff --git a/Virtualization/figures/vasi_download_request_specifier.gif b/LoPAR/figures/vasi_download_request_specifier.gif similarity index 100% rename from Virtualization/figures/vasi_download_request_specifier.gif rename to LoPAR/figures/vasi_download_request_specifier.gif diff --git a/Virtualization/figures/vasi_operation_request_specifier.gif b/LoPAR/figures/vasi_operation_request_specifier.gif similarity index 100% rename from Virtualization/figures/vasi_operation_request_specifier.gif rename to LoPAR/figures/vasi_operation_request_specifier.gif diff --git a/LoPAR/pom.xml b/LoPAR/pom.xml new file mode 100644 index 0000000..aef46c3 --- /dev/null +++ b/LoPAR/pom.xml @@ -0,0 +1,147 @@ + + + + + org.openpowerfoundation.docs + workgroup-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + + + LoPAR-Platform + + jar + + + LoPAR + + + + + 0 + + + + + + + + + org.openpowerfoundation.docs + + openpowerdocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + ${comments.enabled} + LoPAR-Platform + 1 + UA-17511903-1 + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + book/appendix nop + book/chapter nop + chapter toc,title + chapter/section nop + section toc + part toc,title + qandadiv toc + qandaset toc + reference toc,title + set toc,title + + + 1 + 3 + 1 + + + LoPAR + + + LoPAR + + + workgroupNotes + + + + + + workgroupConfidential + + + + + + review + + + + + + + + true + . + + + bk_main.xml + + + + + ${basedir}/../glossary/glossary-terms.xml + 1 + www.openpowerfoundation.org + + + + + diff --git a/common/sec_LoPAR_audience.xml b/LoPAR/sec_LoPAPR_audience.xml similarity index 100% rename from common/sec_LoPAR_audience.xml rename to LoPAR/sec_LoPAPR_audience.xml diff --git a/common/sec_LoPAR_conventions.xml b/LoPAR/sec_LoPAPR_conventions.xml similarity index 100% rename from common/sec_LoPAR_conventions.xml rename to LoPAR/sec_LoPAPR_conventions.xml diff --git a/common/sec_LoPAR_goals.xml b/LoPAR/sec_LoPAPR_goals.xml similarity index 100% rename from common/sec_LoPAR_goals.xml rename to LoPAR/sec_LoPAPR_goals.xml diff --git a/common/sec_LoPAR_reading.xml b/LoPAR/sec_LoPAPR_reading.xml similarity index 100% rename from common/sec_LoPAR_reading.xml rename to LoPAR/sec_LoPAPR_reading.xml diff --git a/Error Handling/ch_error_codes.xml b/LoPAR/sec_error_codes.xml similarity index 98% rename from Error Handling/ch_error_codes.xml rename to LoPAR/sec_error_codes.xml index ac42c69..9975d8a 100644 --- a/Error Handling/ch_error_codes.xml +++ b/LoPAR/sec_error_codes.xml @@ -1,7 +1,7 @@ - Error Codes - +
Displaying Codes on the Standard Operator Panels - + - + - R1-R1--1. Platform Implementation: Platforms must display @@ -38,9 +38,9 @@ first line. - + - R1-R1--2. Platform Implementation: Platforms must display @@ -49,9 +49,9 @@ display (if available). - + - R1-R1--3. Platform Implementation: When a platform displays @@ -61,17 +61,17 @@ available). - + - + The following describes in more detail the standard platform usage of operator panel LEDs or LCDs for the display of firmware progress and error codes. - + - - Progress codes: Progress codes + + Progress codes: Progress codes from the system firmware and service processor firmware are 4 hex digits in the range from 0x8000 through 0xFFFF. Codes are displayed in the 4 character positions of a 1x4 @@ -79,12 +79,12 @@ progress codes are displayed on top of (overlaying) the previous one. If the system “hangs”, the last displayed progress code is left on the display. - + - Error codes: Error codes are 8 - hex digits, as defined in + Error codes: Error codes are 8 + hex digits, as defined in . These codes are displayed by either boot ROM Power On Self Test (POST) or the service processor. If a critical error is detected which prevents a successful boot or results in @@ -97,11 +97,11 @@ normally or in a degraded mode, the associated error codes are not displayed, but are reported to the OS via the POST error log and the RTAS event-scan service. - + - Location Codes: Location codes + Location Codes: Location codes describe the physical location of the most probable failing part associated with an error code. When an error code is displayed on the first line of a 2x16 LCD, the location @@ -110,37 +110,37 @@ system is reset or powered down. Location codes for POST errors are also displayed on any system console (graphic or tty), on the next line below the error code. - +
- +
Firmware Error Codes - + The error code is an 8-character (4-byte) hexadecimal code produced by firmware to identify the potential failing function or FRU in a system. It consists of 5 source code characters and 3 reason code characters. Individual characters within the error code have specific field definitions, as defined in the following tables. - + - + - R1-R1--1. Platform Implementation: To indicate the occurrence of a critical platform error, platforms must display (either on an - operator panel or console) an 8-digit hex error code as defined in - and + operator panel or console) an 8-digit hex error code as defined in + and . - + - + Service Reference Code (SRC) Field Layout @@ -269,10 +269,10 @@ S2 - Where applicable, use the lower nibble of the + Where applicable, use the lower nibble of the - base class code for the IOA definition (see + base class code for the IOA definition (see ). Only 00 to 0C are currently defined in Revision 2.1, therefore the high nibble is always zero. (There is a potential exposure that the high @@ -280,7 +280,7 @@ 13 base classes defined which include every device class, with 3 remaining characters for future extension by the PCI SIG. Therefore the exposure is in the far future.) For non-PCI - devices, use base class 0 to extend the definition (see + devices, use base class 0 to extend the definition (see ). @@ -289,13 +289,13 @@ S3-S4 - Where applicable, use the + Where applicable, use the - subclass code for IOA definition (see + subclass code for IOA definition (see ). Also, extend the definition to include non-PCI devices where it is not fully - utilized by PCI specification (see + utilized by PCI specification (see ). @@ -1274,7 +1274,7 @@
- +
- - + +
diff --git a/Error Handling/sec_error_introduction.xml b/LoPAR/sec_error_introduction.xml similarity index 91% rename from Error Handling/sec_error_introduction.xml rename to LoPAR/sec_error_introduction.xml index 20fdebb..b5e8adb 100644 --- a/Error Handling/sec_error_introduction.xml +++ b/LoPAR/sec_error_introduction.xml @@ -1,7 +1,7 @@ -
- + Introduction - + RTAS provides a mechanism which helps OSs avoid the need for platform-dependent code that checks for, or recovers from, errors or exceptional conditions. The mechanism is used to return information about @@ -31,28 +31,28 @@ voltage out-of-bounds) which may need OS attention. This permits RTAS to pass hardware event information to the OS in a way which is abstracted from the platform hardware. This mechanism primarily presents itself to the OS - via two RTAS functions, - event-scan and - check-exception, which are described further in + via two RTAS functions, + event-scan and + check-exception, which are described further in . A further RTAS function, rtas-last-error, is also provided to return information about hardware failures detected specifically within an RTAS call. - - The + + The event-scan function is called periodically to check for the presence or past occurrence of a hardware event, such as a soft failure or voltage condition, which did not cause a program exception or interrupt (for example, an ECC error detected and corrected by background scrubbing - activity). The + activity). The check-exception function is called to provide further detail on what platform event has occurred when certain exceptions or interrupts are signaled. The events reported by these two functions are mutually exclusive on any given platform; that is, a platform may choose to - notify the OS of a particular event type either through - event-scan or through an interrupt and + notify the OS of a particular event type either through + event-scan or through an interrupt and check-exception, but not both. - + Since firmware is platform-specific, it can examine hardware registers, can often diagnose many kinds of hardware errors down to a root cause, and may even perform some very limited kinds of error recovery on @@ -63,13 +63,13 @@ involvement. Firmware may not, in many cases, be able to determine all the details of an error, so there are also returned values which indicate this fact. Firmware may optionally provide extended error diagnostic - information, as described in + information, as described in . - + The abstractions provided by this architecture enable the handling of most platform errors and events without integrating platform-specific code into each supported OS. - + Architecture Note: It is not a goal of the firmware to diagnose all hardware failures. Most I/O device failures, for example, will be detected and recovered by an associated device driver. Firmware attempts to @@ -81,5 +81,5 @@ contain specific hardware knowledge, or could use firmware to collect a minimum set of error information which could then be used by diagnostics to further analyze the cause of the error. - +
diff --git a/LoPAR/sec_pa_processor_binding_terms.xml b/LoPAR/sec_pa_processor_binding_terms.xml new file mode 100644 index 0000000..3ec8719 --- /dev/null +++ b/LoPAR/sec_pa_processor_binding_terms.xml @@ -0,0 +1,174 @@ + + +
+ + Terms + + This standard uses technical terms as they are defined in the + IEEE Std 1275-1994 Standard and other + documents cited in “References”, plus the following + terms: + + + + + core, core specification, core document + + Refers to IEEE Std 1275-1994 Standard for Boot (Initialization, + Configuration) Firmware, Core Practices and Requirements + + + + + core errata + + Refers to Core Errata, IEEE P1275.7 + + + + + effective address + + The 64- or 32-bit address computed by the processor + when executing a Storage Access or Branch instruction, or when fetching the + next sequential instruction. If address translation is disabled, the real + address is the same as the effective address. If address translation is + enabled, the real address is determined by, but not necessarily identical + to, the effective address. + + + + + linkage area + + An area within the stack that is reserved for saving + certain registers across procedure calls in PA run-time models. This area + is reserved by the caller and is allocated above the current stack pointer + (%r1). + + + + + Open Firmware (OF) + + The firmware architecture defined by + and + , or, when used as an adjective, + a software component compliant with the core specification and + errata. + + + + + procedure descriptor + + A data structure used by some PA run-time models + to represent a C “pointer to procedure”. The first word of this + structure contains the actual address of the procedure. + + + + + processor bus + + The bus that connects the CPU chip to the system. + + + + + real address + + An address that the processor presents on the processor + bus. + + + + + real-mode + + The mode in which OF and its client are running with + translation disabled; all addresses passed between the client and OF are + real (i.e., hardware) addresses. + + + + + segmented address translation + + The process whereby an Effective Address (EA) is translated into a + Virtual Address (VA) and the virtual address is translated into a Real + Address (RA). (see + and Book III of + for more detail.) + + + + + suspend + + A form of Power Management characterized by a fast recovery + to full operation. Typically, system memory will not be powered off while + in the suspend state. + + + + + Table of Contents (TOC) + + A data structure used by some PA run-time models that is used for + access to global variables and for inter-module linkage. When a TOC is + used, + %r2 contains its base address. + + + + + Virtual Address + + In IEEE 1275 parlance, the address that a program uses to access + a memory location or + memory-mapped device register. Depending on the presence or absence of + memory mapping hardware in the system, and whether or not that mapping + hardware is enabled, a virtual address may or may not be the same as the + physical (real) address that appears on an external bus. The IEEE 1275 + definition of “virtual address” corresponds to The PA's + definition of “effective address.” Except as noted, this + document uses the IEEE 1275 definition of virtual address. + + In PA parlance, an internal address within the PA address + translation mechanism, used + as in intermediate term in the translation of an effective address to the + corresponding real address. + + + + + virtual-mode + + The mode in which OF and its client share a single + virtual address space, and address translation is enabled; all addresses + passed between the client and OF are virtual (translated) addresses. + + + + +
diff --git a/DeviceTree/ch_devtree_terms.xml b/LoPAR/sec_papr_binding_terms.xml similarity index 63% rename from DeviceTree/ch_devtree_terms.xml rename to LoPAR/sec_papr_binding_terms.xml index 4979d94..c894cdc 100644 --- a/DeviceTree/ch_devtree_terms.xml +++ b/LoPAR/sec_papr_binding_terms.xml @@ -1,7 +1,7 @@ - - + xml:id="sec_papr_binding_terms"> + Terms - + This standard uses technical terms as they are defined in the IEEE Std 1275-1994 Standard and other documents cited in “References”, plus the following terms: - + ARP @@ -73,21 +73,9 @@ - effective address - - The 64- or 32-bit address computed by the processor - when executing a Storage Access or Branch instruction, or when fetching the - next sequential instruction. If address translation is disabled, the real - address is the same as the effective address. If address translation is - enabled, the real address is determined by, but not necessarily identical - to, the effective address. - - - - - ELF Executable and Linking Format + ELF - A binary object file format defined by + Executable and Linking Format. A binary object file format defined by that is used to represent client programs in OF for PA. @@ -97,7 +85,7 @@ FDISK Refers to the boot-record and partition table format used by - MS-DOS, as defined in + MS-DOS, as defined in . @@ -152,16 +140,6 @@ - - linkage area - - An area within the stack that is reserved for saving - certain registers across procedure calls in PA run-time models. This area - is reserved by the caller and is allocated above the current stack pointer - (%r1). - - - NVRAM @@ -174,8 +152,8 @@ Open Firmware (OF) - The firmware architecture defined by - and + The firmware architecture defined by + and , or, when used as an adjective, a software component compliant with the core specification and errata. @@ -193,27 +171,11 @@ PE - Portable Executable. A binary object file format defined by + Portable Executable. A binary object file format defined by . - - procedure descriptor - - A data structure used by some PA run-time models - to represent a C “pointer to procedure”. The first word of this - structure contains the actual address of the procedure. - - - - - processor bus - - The bus that connects the CPU chip to the system. - - - PROM @@ -221,14 +183,6 @@ - - real address - - An address that the processor presents on the processor - bus. - - - real-mode @@ -253,17 +207,6 @@ - - segmented address translation - - The process whereby an Effective Address (EA) is translated into a - Virtual Address (VA) and the virtual address is translated into a Real - Address (RA). (see - and Book III of - for more detail.) - - - suspend @@ -273,16 +216,6 @@ - - Table of Contents (TOC) - - A data structure used by some PA run-time models that is used for - access to global variables and for inter-module linkage. When a TOC is - used, - %r2 contains its base address. - - - TFTP @@ -297,26 +230,6 @@ - - Virtual Address - - In IEEE 1275 parlance, the address that a program uses to access - a memory location or - memory-mapped device register. Depending on the presence or absence of - memory mapping hardware in the system, and whether or not that mapping - hardware is enabled, a virtual address may or may not be the same as the - physical (real) address that appears on an external bus. The IEEE 1275 - definition of “virtual address” corresponds to The PA's - definition of “effective address.” Except as noted, this - document uses the IEEE 1275 definition of virtual address. - - In PA parlance, an internal address within the PA address - translation mechanism, used - as in intermediate term in the translation of an effective address to the - corresponding real address. - - - virtual-mode @@ -326,5 +239,5 @@ - - + +
diff --git a/RTAS/ch_rtas_call_defn.xml b/LoPAR/sec_rtas_call_defn.xml similarity index 99% rename from RTAS/ch_rtas_call_defn.xml rename to LoPAR/sec_rtas_call_defn.xml index f5bd0f7..bf471fb 100644 --- a/RTAS/ch_rtas_call_defn.xml +++ b/LoPAR/sec_rtas_call_defn.xml @@ -15,7 +15,7 @@ limitations under the License. --> - - - + + + + + + + + + + + +
diff --git a/LoPAR/sec_rtas_configure_kernel_dump.xml b/LoPAR/sec_rtas_configure_kernel_dump.xml new file mode 100644 index 0000000..da9e219 --- /dev/null +++ b/LoPAR/sec_rtas_configure_kernel_dump.xml @@ -0,0 +1,621 @@ + + +
+ <emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call + + This RTAS call is used to register and unregister with the platform + a data structure describing kernel dump information. This dump + information is preserved as needed by the platform in support of a + platform assisted kernel dump option. + + + + R1--1. + + For the Configure Platform Assisted Kernel Dump + option: The platform must implement the + ibm,configure-kernel-dump RTAS call using the + argument call buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,configure-kernel-dump</emphasis> + + + + + + + + Parameter Type + + + Name + + + Values + + + + + In + + + + Token + + + + Token for + ibm,configure-kernel-dump + + + + + + Number Inputs + + + + 3 + + + + + + Number Outputs + + + + 1 + + + + + + Command + + + + 1: Register for future kernel dump + 2: Unregister for future kernel dump + 3: Complete/Invalidate current kernel dump + + + + + + Work_buffer_address + + + + When command is 1: Register for future kernel dump, + points to a structure as defined in + . + + + + + + Work_buffer_length + + + + Length of Kernel Dump Memory Structure when defined + above + + + + + Out + + + + Status + + + + 0: Success + -1: Hardware Error + -2: Busy + -3: Parameter Error + -9: Dump Already Registered + -10: Dump Active + 990x:Extended Delay + + + + +
+ + + + + R1--2. + + For the Configure Platform Assisted Kernel Dump + option: The work-buffer address and work-buffer-length for the + ibm,configure-kernel-dump RTAS call must point to an + RMR-memory buffer that contains the structures described in + , whenever the command is 1, + register for future kernel dump; otherwise the call may return -3, + “Parameter Error.” + The Dump Memory Structure specified in + is passed by the operating + system during a + ibm,configure-kernel-dump RTAS call. It is also + reported by the platform using the + ibm,kernel-dump RTAS property after a dump has been + initiated. + + + Kernel Assisted Dump Memory Structure + + + + + + + + + + + Header + + + + + + + + Offset + + + Number of Bytes + + + Value + + + + + 0x0 + + + 4 + + + Dump Format Version = 0x00000001 + + + + + 0x4 + + + 2 + + + Number of Kernel Dump Sections + + + + + 0x6 + + + 2 + + + Dump Status Flags + A bit mask with value + 0x8000 = Dump performed (Set to 0 by caller of the + ibm,configure-kernel-dump call) + 0x4000 = Dump was triggered by the previous system boot + (set by platform) + 0x2000 = Dump error occurred (set by platform) + All other bits reserved + + + + + 0x8 + + + 4 + + + Offset to first Kernel Dump Section, offset from the + beginning of the Structure + + + + + 0xc + + + 4 + + + Number of bytes in a block of the dump-disk, if data to + be written to a dump-disk, If not, should be set to 0 + (indicating the no disk dump option.) + + + + + 0x10 + + + 8 + + + Starting block# offset on dump-disk (set to 0 for the no + disk dump option) + + + + + 0x18 + + + 8 + + + Number of blocks on dump-disk usable for dump (set to 0 + for the no disk dump option) + + + + + 0x20 + + + 4 + + + Offset from start of structure to a Null-terminated + Dump-disk path string (set to 0 for the no disk dump + option) + + + + + 0x24 + + + 4 + + + Maximum time allowed (milliseconds) after + Non-Maskable-Interrupt for the OS to call + ibm,configure-kernel-dump + Function 2 (unregister) to prevent an + automatic dump-reboot (set to 0 to disable the automatic + dump-reboot function) + + + + + + Dump-disk Path String + + + + + + Offset specified above + + + Varies + + + Null-terminated Dump-disk path string specifying the + dump-disk. If no disk dump option is indicated, this section is + not included. + + + + + + First Kernel Dump Section + + + + + + Offset specified above + + + 4 + + + Dump Request Flags: + A bit-mask + Bit 0x00000001 When set, firmware to copy source data to + partition memory. This option must be selected if no disk dump + option is indicated. + All other bit values reserved + + + + + Section Start+4 + + + 2 + + + Source Data type, describes section of dump memory being + described + 0x0001 = CPU State Data + 0x0002 = Hardware Page Table for Real Mode Region + 0x0011 = Real Mode Region + 0x0012 = Dump OS identified string (identifies that the + dump is for a particular OS type and version) + 0x0100 - 0xFFFF OS defined source types + All Other values reserved + + + + + Section Start+6 + + + 2 + + + Dump Error Flags (set by platform) + Bit mask + 0x8000 = Invalid section data type + 0x4000 = Invalid source address + 0x2000 = Requested section length exceeds source + 0x1000 = Invalid partition destination address + 0x0800 = Partition memory destination too small + + + + + Section Start+8 + + + 8 + + + Source address (logical address if section came from + partition memory, or byte offset if section is platform + memory) + + + + + Section Start+16 + + + 8 + + + Requested data length, represents number of bytes to + dump + + + + + Section Start+24 + + + 8 + + + Actual data length, number of bytes dumped + + + + + Section Start+32 + + + 8 + + + Destination address, logical address used for sections + not written to disk by the platform, always required for a Real + mode region section and for all sections when the no disk dump + option is used. + + + + + + Subsequent Sections + + + + + + Previous Section Start+40 + + + Start of Next Section + + + A total of up to nine additional 40 bytes sections with + values as described in the First Section may be specified so + long as the entire structure does not exceed 512 bytes for + version 1. + + + + +
+ + + + + R1--3. + + ibm,os-term RTAS call, or on a system reset without + an + ibm,nmi-interlock RTAS call, if the platform has a + dump structure registered through the + ibm,configure-kernel-dump call, the platform must + process each registered kernel dump section as required and, when + available, present the dump structure information to the operating system + through the + “ibm,kernel-dump” property, updated with + status for each dump section, until the dump has been invalidated through + the + ibm,configure-kernel-dump RTAS call. + + + + + R1--4. + + If ibm,configure-kernel-dump RTAS call is made to + register or unregister for a dump while a dump is currently active, the + platform must return a + Status of -9, “Dump Active” indicating + that a dump has been copied by the platform and a call must be made to + complete/invalidate the active dump before another call to register or + unregister a dump can be completed successfully. + + + + + R1--5. + + If ibm,configure-kernel-dump RTAS call is made to + register a dump after a dump has already been registered by a call, the + platform must return a + Status of -8, “Dump Already Registered” + unless an intervening call was made to invalidate the previously + registered dump. + + + + + R1--6. + + For the Configure Platform Assisted Kernel Dump + Option: Partition memory not specifically mentioned in the call + structure must be preserved by the platform at the same location as + existed prior to the os termination or platform reboot. + + + + + R1--7. + + For the Configure Platform Assisted Kernel Dump + Option: The platform must present the RTAS property, + “ibm,configure-kernel-dump-sizes” in the + OF device tree, which describes how much space is required to store dump + data for the firmware provided dump sections, where the firmware defined + dump sections are: + + + + 0x0001 = CPU State Data + + + + 0x0002 = Hardware Page Table for Real Mode Region + + + + + + + R1--8. + + For the Configure Platform Assisted Kernel Dump + Option: The platform must present the RTAS property, + “ibm-configure-kernel-dump-version” in + the OF device tree. + + + + + R1--9. + + For the Configure Platform Assisted Kernel Dump + Option: After a dump registration is disabled (for example, by + a partition migration operation), calls to + ibm,os-term must return to the OS as though a dump + was not registered. + + Programming Note: The intended flow of interactions + that utilize this call is as follows: + + + + The OS registers sections of memory for dump preservation during + OS initialization + + + + The OS terminates abnormally + + + + The Platform moves registered sections of memory as instructed + during dump registration. + + + + The Partition reboots and provides the prior registration data + in the device tree. + + + + The OS writes the preserved memory regions to disk before using + those memory regions for regular use + + + + The OS completes/invalidates current dump status. + + + + 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/LoPAR/sec_rtas_dma_window.xml b/LoPAR/sec_rtas_dma_window.xml new file mode 100644 index 0000000..de5c0b5 --- /dev/null +++ b/LoPAR/sec_rtas_dma_window.xml @@ -0,0 +1,1101 @@ + + +
+ + DMA Window Manipulation Calls + + DMA windows for a PE can be changed by the OS when the platform + implements the Dynamic DMA Windows (DDW) option for a PE. The occurrence + of the + “ibm,ddw-applicable” property in any node + of the OF Device Tree indicates that the platform implements the DDW + option, but that property is required to be in the bridge above a PE in + order for the DDW RTAS call to be applicable for the PE. That is, DDW may + be applicable to some PEs in a platform and not for others. + The platform may implement the DDW RTAS calls even when the OS does + not support these, because they are not required to be used by the OS, + because there is always a default window initially allocated below 4 GB, + as specified by the + “ibm,dma-window” property. During + partition migration, these RTAS calls may come and go, but so will the + “ibm,ddw-applicable” property as the + nodes in which those are supported come or go. + The following is an example of how an OS may grab all DMA window + resources allocated for a PE: + + + + If the default window (as specified by the + “ibm,dma-window” property for the PE) is + not needed, then call + ibm,remove-pe-dma-window for the PE, specifying the + default window LIOBN, to make the maximum resources available for the + ibm,create-pe-dma-window RTAS call. + + + + Call + ibm,query-pe-dma-window for the PE to get the + Windows Available and + PE TCEs available for the PE. If the + Windows Available field indicates 1 or more and the + PE TCEs field is non-zero, then continue. + + + + Call ibm,create-pe-dma-window for the PE, specifying the + size based on the + PE TCEs field obtained from the + ibm,query-pe-dma-window RTAS call in step + and on the I/O page size being + specified. + + + + If the Windows Available field indicated 2 or more in step + , then go back to step + and repeat, otherwise + finished. + + + + Software Implementation Note: The general expectation + is that if the + “ibm,ddw-applicable” property exists for + a PE, that the OS will be able to generate one or more windows whose + total size is larger than what is available via the default window. This + requires either additional TCEs being available or that I/O page sizes + other than 4 KB are available and the PE can use the largest I/O page + size (the default window using only the 4 KB I/O page size). If not, then + removing the default window would only allow re-allocation of the same + size window at a different bus address (that is, same number of TCEs and + same I/O page size). However, it may be possible for this to happen, in + which case the platform may indicate that DDW is available to a PE, but + removal of the default window will only allow creation of the same size + window. An example is when a larger I/O page size is available but only + the TCEs in the default window are available, and the PE cannot make use + of the larger page size. + + + + R1--1. + + For the Dynamic DMA Windows (DDW) option: The + platform must implement all of the following RTAS calls: + ibm,query-dma-window, + ibm,create-dma-window, and + ibm,remove-dma-window. + + + + + R1--2. + + For the Dynamic DMA Windows (DDW) option: The + platform must provide the + “ibm,ddw-applicable” property in the OF + Device Tree in the bridge above each PE for which the DDW option is + supported. + + + + + R1--3. + + For the Dynamic DMA Windows (DDW) option: The + software must not call the + ibm,query-dma-window, + ibm,create-dma-window, or + ibm,remove-dma-window RTAS calls in the absence of + the + “ibm,ddw-applicable” property for the PE, + otherwise the call returns a + Status of -3 (Parameter error), and when the property + does exist, software must use the token values specified in the + “ibm,ddw-applicable” property for these + RTAS calls. + + + + + R1--4. + + For the Dynamic DMA Windows (DDW) option: The + platform must provide a default DMA window for each PE, and all of the + following must be true: + + + + The window is defined by the + “ibm,dma-window” property in the OF + device tree. + + + + The window is defined with 4 KB I/O pages. + + + + The window is located entirely below 4 GB. + + + + + + + R1--5. + + For the Dynamic DMA Windows (DDW) option: + The platform must remove any DMA windows created by the + ibm,create-pe-dma-window RTAS call for a PE and must + restore the default DMA window (if it was removed) for the PE, as + originally defined by the + “ibm,dma-window” properties for the PE, + in each of the following cases: + + + + On a reboot of the partition + + + + On a DR isolate operation that encompasses the PE + + + + + + + R1--6. + + For the Dynamic DMA Windows (DDW) option: + In Requirement + , the platform must provide the + same LIOBN, location, and size as specified in the + “ibm,dma-window” property in the OF + Device Tree for the device. + + + + +
+ <emphasis>ibm,query-pe-dma-window</emphasis> + + This RTAS call allows for the discovery of the resources necessary + to make a successful subsequent call to + ibm,create-dma-window. + + If the ibm,query-pe-dma-window RTAS call is made with Number Outputs + equal to 6, and the “ibm,ddw-extensions” + property does not include list index of 3, + then the call will return a Status of -3 (Invalid Parameter). + + + + R1--1. + + RTAS must implement a + ibm,query-pe-dma-window call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,query-pe-dma-window</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,query-pe-dma-window + + + + + + Number Inputs + + + + 3 + + + + + + Number Outputs + + + + 5 or 6. The value 6 may be used when the ibm,ddw-extensions property + in the PHB node specified by this call indicates support for a 64-bit value of + PE TCEs. See . + + + + + + Config_addr + + + + PE configuration address (Register fields set to + 0) + + + + + + PHB_Unit_ID_Hi + + + + Represents the most-significant 32-bits of the Unit ID of + the PHB that corresponds to the + config_addr + + + + + + PHB_Unit_ID_Low + + + + Represents the least-significant 32-bits of the Unit ID + of the PHB that corresponds to the + config_addr + + + + + Out + + + + Status + + + + 0: Success + -1: Hardware Error + -3: Parameter error + + + + + Windows Available + + + Number of additional DMA windows that can be created for + this PE. If the value is 0 and the default window (as specified + by the + “ibm,dma-window” property for + the PE) has not been yet removed via the + ibm,remove-pe-dma-window RTAS call for that + window, and if the default window is not needed, then removal + of the default window makes at least one window + available. + + + + + PE TCEs hi + + + Represents the most-significant 32-bits of the largest contiguous + block of TCEs allocated specifically for (that is, are reserved for) this PE. + + + + + PE TCEs lo + + + Represents the least-significant 32-bits of the largest contiguous block + of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement + . + + + + + IO Page Sizes + + + I/O Page Size Support. I/O page sizes supported for this + PE. This is a bit significant field, defined as follows: + Bits 0 - 23 reserved + 24 = 16 GB page size supported + 25 = 256 MB page size supported + 26 = 128 MB pages supported + 27 = 64 MB page size supported + 28 = 32 MB page size supported + 29 = 16 MB page size supported + 30 = 64 KB page size supported + 31 = 4 KB page size supported + + + + + Migration Capable + + + H_MIGRATE_DMA Mask. Mask to indicate for which page sizes + (as specified in the I/O Page Size Support field), that + H_MIGRATE_DMA is supported (for this PE). This is a bit + significant field, with the bits defined to align to the bits + in the I/O Page Size Support field. + + + + +
+ + + + + R1--2. + + For the Dynamic DMA Windows (DDW) option: + TCE resources returned in the + PE TCEs parameter of the + ibm,query-dma-window RTAS call must be allocated to + the PE specified by the PE configuration address specified in the call, + and must be available to a subsequent + ibm,create-dma-window RTAS call for that PE. + + + + +
+ +
+ <emphasis>ibm,create-pe-dma-window</emphasis> + + This call allows the creation of a new DMA window, given the size + of the DMA window, I/O page size, and the PE to which it is associated. + The return from the call includes the LIOBN of the new DMA window, the + starting I/O address of the DMA window, and size. + + Software Implementation Note: Software is expected to + not attempt to create a DMA window that is larger than possible, or + create more DMA windows than is possible, otherwise the + ibm,create-pe-dma-window will return a + Status of -3 (Parameter Error). Thus, the OS is + expected to use the + ibm,query-pe-dma-window first and not ask to create a + window that consumes more resources than those that are available to the + PE. + + + + R1--1. + + For the Dynamic DMA Windows (DDW) option: RTAS must + implement the + ibm,create-dma-window call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,create-pe-dma-window</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,create-pe-dma-window + + + + + + Number Inputs + + + + 5 + + + + + + Number Outputs + + + + 4 + + + + + + Config_addr + + + + PE configuration address (Register fields set to + 0) + + + + + + PHB_Unit_ID_Hi + + + + Represents the most-significant 32-bits of the Unit ID of + the PHB that corresponds to the + config_addr + + + + + + PHB_Unit_ID_Low + + + + Represents the least-significant 32-bits of the Unit ID + of the PHB that corresponds to the + config_addr + + + + + I/O Page Size + + + The value n, where 2 + n is the requested I/O page size. Only page + sizes obtained from the + ibm,query-pe-dma-window RTAS call for the + PE are allowed. Values of n from 0-11 are invalid. + + + + + Requested Window Size + + + The value n, where 2 + n is the requested DMA window size. + + + + + Out + + + + Status + + + + 990x: Extended delay, where x is a number 0-5 (see + text) + 0: Success (window created) + -1: Hardware Error + -2: Busy, try again later + -3: Parameter Error + + + + + + LIOBN + + + + LIOBN of the DMA window created by this call, if any. If + no DMA window was created (that is, if the + Status is not 0), then this field is + present but not used. + + + + + I/O Starting Address Hi + + + Represents the most-significant 32-bits of the starting + address on the I/O bus for the DMA window created by this call, + if any. If no DMA window was created (that is, if the + Status is not 0), then this field is + present but not used. + + + + + I/O Starting Address Low + + + Represents the least-significant 32-bits of the starting + address on the I/O bus for the DMA window created by this call, + if any. If no DMA window was created (that is, if the + Status is not 0), then this field is + present but not used. + + + + +
+ + + + + R1--2. + + For the Dynamic DMA Windows (DDW) option: The + ibm,create-pe-dma-window RTAS call must return a + Status of 0 (Success) only if a window with the + requested attributes is created, and must not create a new window if a + non-0 + Status is returned. + + + + +
+ +
+ <emphasis>ibm,remove-pe-dma-window</emphasis> + + This RTAS call allows for the removal of PE DMA windows, including + those created with the + ibm,create-pe-dma-window RTAS call as well as the + default window specified by the + “ibm,dma-window” property for the PE. All + created DMA windows will be removed by the platform, and the default DMA + window restored, on a partition reboot, on a DR isolate operation (see + Requirement + and + ), or if the last remaining DMA + window for the PE is removed and that window is not the default DMA + window (see Requirements + and + ). After removal of a DMA + window, software needs to use the + ibm,query-pe-dma-window RTAS call to find out what + resources are available to the PE for subsequent + ibm,create-pe-dma-window RTAS call. + + + + R1--1. + + For the Dynamic DMA Windows (DDW) option: RTAS must + implement the + ibm,remove-dma-window call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,remove-pe-dma-window</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,remove-pe-dma-window + + + + + + Number Inputs + + + + 1 + + + + + + Number Outputs + + + + 1 + + + + + + LIOBN + + + + LIOBN of the DMA window to be removed. + + + + + Out + + + + Status + + + + 0: Success + -1: Hardware Error + -3: Parameter error + + + + +
+ + + + + R1--2. + + For the Dynamic DMA Windows (DDW) option: The caller + of the + ibm,remove-pe-dma-window RTAS call must assure that + the TCE table specified by the + LIOBN field does not contain any valid mappings at + the time of the call (that is, that the window is not being used). + + + + + R1--3. + + For the Dynamic DMA Windows (DDW) option: + The platform must + restore the default DMA window for the PE on a call to the + ibm,remove-pe-dma-window RTAS call when all of the + following are true: + + + + The call removes the last DMA window remaining for the + PE. + + + + The DMA window being removed is not the default window. + + + + + + + R1--4. + + For the Dynamic DMA Windows (DDW) option: + In Requirement + , the platform must provide the + same LIOBN, location, and size as specified in the + “ibm,dma-window” property in the OF + Device Tree for the PE. + + + + +
+ +
+ Extensions to Dynamic DMA Windows + + Platforms supporting the DDW option implement extensions described + in this section. These extensions include: adding the + “ibm,ddw-extensions” property see + to those nodes that include the + “ibm,ddw-applicable” property, and + implementing the functional extensions specified for the architectural + level in + . The + “ibm,ddw-extensions” property value is a + list of integers the first integer indicates the number of extensions + implemented and subsequent integers, one per extension, provide a value + associated with that extension. Thus the property value is designed to + grow over time in such a way as to enable earlier client programs to + ignore later firmware extensions and later client programs to operate on + back level firmware. For this level of compatibility to work, the client + code needs to ignore extensions beyond what were defined when the client + code was written, and be prepared to operate on back level platforms t at + do not implement all the extensions that were defined when the client + code was written. + + + DDW Option Extensions + + + + + + + + + DDW Option LoPAR or PAPR Level + + + + + + “ibm,ddw-extensions” list + index + + + + + Value Definition + + + + + + + + 2.7 + + + 2 + + + Token of the i + bm,reset-pe-dma-windows RTAS Call + + + + + 2.7 + + + 3 + + + Value of 1 indicates the OS may invoke RTAS ibm,query-pe-dma-window + with Number Outputs equal to 6. Other values are reserved. + + + + +
+ + + + R1--1. + + For compatibility with changing extensions to the Dynamic DMA + Windows (DDW) option: The client program must ignore extensions + as represented by + “ibm,ddw-extensions” value list integers + beyond those defined when the client code was written. + + + + + R1--2. + + For compatibility with changing extensions to the Dynamic DMA + Windows (DDW) option: The client program must be prepared to + operate on back level platforms that do not implement all the extensions + that were defined when the client code was written, including no + extensions at all. + + + + + +
+ <emphasis>ibm,reset-pe-dma-windows</emphasis> + The + ibm,reset-dma-windows call resets the TCE table + allocation for the PE to its boot time value as communicated in the + “ibm,dma-window” OF Device Tree property + in the for the PE. + + + + R1--1. + + For the Dynamic DMA Windows (DDW) option starting with + IBM Power Architecture Platform Requirements (PAPR) + level 2.7: RTAS must implement the + ibm,reset-dma-windows call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,reset-pe-dma-windows</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + + + + + + + Number Inputs + + + + 3 + + + + + + Number Outputs + + + + 1 + + + + + + config_addr + + + + PE configuration address + + + + + PHB_Unit_ID_HI + + + Represents the most-significant 32-bits of the Unit ID of + the PHB that corresponds to the config_addr + + + + + PHB_Unit_ID_Low + + + Represents the least-significant 32-bits of the Unit ID + of the PHB that corresponds to the config_addr + + + + + Out + + + + Status + + + + 0: Success + -1: Hardware Error + -2: Busy, Try again later + -3: Parameter error + + + + +
+ + + + + R1--2. + + For the Dynamic DMA Windows (DDW) option starting with + IBM Power Architecture Platform Requirements (PAPR) + level 2.7: The caller of the + ibm,reset-pe-dma-windows RTAS call must assure that + the TCE table(s) assigned to the PE specified by the + config_addr field contain no valid mappings at the + time of the call (that is, that the window(s) is not being used). + + + + + R1--3. + + For the Dynamic DMA Windows (DDW) option starting with + IBM Power Architecture Platform Requirements (PAPR) + level 2.7: On a call to + ibm,restore-pe-dma-windows, the platform must + restore the default DMA window per the values provided in the + “ibm,dma-window” Tree property + in the for the PE (same LIOBN, location, and size). + + + + + +
+ +
+ +
diff --git a/Error Handling/sec_rtas_env_epow.xml b/LoPAR/sec_rtas_env_epow.xml similarity index 100% rename from Error Handling/sec_rtas_env_epow.xml rename to LoPAR/sec_rtas_env_epow.xml diff --git a/RTAS/ch_rtas_environment.xml b/LoPAR/sec_rtas_environment.xml similarity index 93% rename from RTAS/ch_rtas_environment.xml rename to LoPAR/sec_rtas_environment.xml index 230771b..b55e964 100644 --- a/RTAS/ch_rtas_environment.xml +++ b/LoPAR/sec_rtas_environment.xml @@ -1,7 +1,7 @@ - - + Environment - + RTAS provides an interface definition between the OS and the firmware provided by the platform. This chapter defines the calling conventions used by both the OS and the platform’s RTAS firmware. @@ -30,21 +30,21 @@ exceptions disabled. To not interfere with the OS, RTAS may not cause any exceptions, nor can it depend on any particular virtual memory mappings. - All RTAS functions are invoked from the OS by calling the - rtas-call function. The address of this + All RTAS functions are invoked from the OS by calling the + rtas-call function. The address of this function is obtained from OF when - RTAS is instantiated. See Requirement + RTAS is instantiated. See Requirement for more details. RTAS determines - what function to invoke based on the data passed into the - rtas-call function. This section describes the + what function to invoke based on the data passed into the + rtas-call function. This section describes the mechanisms used to invoke the rtas-call function, the machine state, register usage, resource allocation, and the invocation requirements. If the LPAR option is enabled, multiple partitions may exist, each with its own OS instance. This requires some changes to the RTAS - environment. These changes are discussed in + environment. These changes are discussed in . - +
Machine State When RTAS functions are invoked, the calling processor shall have @@ -53,105 +53,105 @@ - R1-R1--1. RTAS must be called in “real - mode,” that is, all address translation must be disabled. Bits MSRIR and + mode,” that is, all address translation must be disabled. Bits MSRIR and MSRDR of the MSR register must be zero. - + - R1-R1--2. RTAS must be called in privileged mode, and the MSRPR bit must be set to 0. - + - R1-R1--3. RTAS must be called with external interrupts disabled, and the MSREE bit must be set to 0. - + - R1-R1--4. RTAS must be called with trace disabled, - and the MSRSE and + and the MSRSE and MSRBE bits must be set to 0. - + - R1-R1--5. RTAS must be - called with floating point disabled, and the - MSRFE0, - MSRFE1, and + called with floating point disabled, and the + MSRFE0, + MSRFE1, and MSRFP bits must be set to 0. - + - R1-R1--6. - RTAS must be called with the MSRSF, - (MSRISF, and ASRV + RTAS must be called with the MSRSF, + (MSRISF, and ASRV bits if applicable on the specific processor) set to match the mode used to instantiate RTAS (0 for - instantiate-rtas or 1 for + instantiate-rtas or 1 for instantiate-rtas-64) and the LE bit set to 0. - + - R1-R1--7. - With the exception of the MSRDR and + With the exception of the MSRDR and MSRRI bits, RTAS must not change the state of the machine by modifying the MSR. - + - R1-R1--8. rtas-call is entered - in a non-recoverable mode, indicated by having the + in a non-recoverable mode, indicated by having the MSRRI bit set equal to 0, then RTAS must not enter a recoverable mode by setting the MSRRI bit to 1. - + - R1-R1--9. - If called with MSRRI equal to 1, + If called with MSRRI equal to 1, then RTAS must protect its own - critical regions from recursion by setting the MSRRI + critical regions from recursion by setting the MSRRI bit to 0 when in the critical regions. Software Implementation Notes: - - + + If the MSRME bit is left enabled, the OS’s exception handler must be aware that RTAS might have been running and that various @@ -162,28 +162,28 @@ There are some provisions for recursive calls to RTAS error - handling functions. Therefore, RTAS should set the MSRRI + handling functions. Therefore, RTAS should set the MSRRI bit to 0 if SRR0/SRR1 or any other RTAS resource is in a state where information could be lost and prohibit recovery. - Requirement + Requirement implies that RTAS must be able to be instantiated in 64-bit mode on platforms that can support 64-bit execution. - - + +
- +
Register Usage - R1-R1--1. Except as @@ -192,9 +192,9 @@ visible register state. - + - R1-R1--2. RTAS must not modify the DEC and registers SPRG0, SPRG1, and SPRG3. @@ -203,8 +203,8 @@ Software Implementation Notes: - - + + RTAS is entered in real mode (with address translation turned off). In this mode, all data accesses @@ -213,7 +213,7 @@ RTAS is free to transparently use the processor specific facilities required to access platform hardware resources. The OS machine check handler can only depend on those registers that are required to be - unchanged (see Requirement + unchanged (see Requirement ). @@ -227,13 +227,13 @@ reservations made via the load and reserve instructions, need not be preserved. - - + +
- +
RTAS Critical Regions - + The OS, when using RTAS, is responsible for protecting RTAS and devices used by RTAS from any simultaneous accesses that could corrupt memory or device registers. Such corruption could be caused by @@ -241,7 +241,7 @@ control register that is also modified by RTAS. In a single processor system, since the MSREE bit is 0 when entering RTAS, a call to RTAS while it is in execution is prevented except for the machine check handler. - This handler may need to call various RTAS services such as + This handler may need to call various RTAS services such as check-exception or system-reboot even if the error was detected while in an RTAS service @@ -256,20 +256,20 @@ - R1-R1--1. - Except as noted in Requirement - and + Except as noted in Requirement + and , the OS must ensure that RTAS is not called while RTAS is in execution and that RTAS is not simultaneously called from different processors in a multi-processor system. - + - R1-R1--2. Any RTAS access to device or I/O registers @@ -277,9 +277,9 @@ transparent to the OS. - + - R1-R1--3. Any device that @@ -288,24 +288,24 @@ However, if the device is only used by the power-off, and system-reboot calls, the property should not be set. - The + The rtas-display-device must be marked with the property “used-by-rtas” if it is a specialized - device only to be accessed via the RTAS + device only to be accessed via the RTAS display-character call and not otherwise shared with the OS - + Software Implementation Note: clarifies when a device should be marked with the “used-by-rtas” property, based on whether it has any interaction with RTAS and/or the OS (with the exception of the - calls listed in Requirement + calls listed in Requirement ). - Use of + <title>Use of <emphasis role="bold"><literal>“used-by-rtas”</literal></emphasis> @@ -378,77 +378,77 @@
- - + + A device which is not normally to be used by the OS must meet one of the following rules. - - + + It must not be included in the OF device tree. - + It must be defined as a “reserved” device node. - + - It must be marked with the + It must be marked with the “used-by-rtas” property in the OF device tree. - + - + - It is assumed that an + It is assumed that an rtas-display-device is used by RTAS. - + - It is assumed that there are no devices other than the + It is assumed that there are no devices other than the rtas-display-device which are used by both RTAS and an “unaware” OS. To allow an aware OS to share a device with RTAS, the device should be marked. - + - It is assumed that the + It is assumed that the rtas-display-device is used by both RTAS and the OS (as coordinated by the OS via display-character) unless it is marked. See - also Requirement + also Requirement . - - + + - + - R1-R1--4. Platforms must be designed such that - accesses to devices that are marked - “used-by-rtas” + accesses to devices that are marked + “used-by-rtas” have no side effects on other registers in the system. - + - R1-R1--5. - Any OS access to devices specified as - “used-by-rtas” + Any OS access to devices specified as + “used-by-rtas” must be made in such a way as to be transparent to RTAS. - + - R1-R1--6. RTAS must not generate any exceptions (for @@ -456,76 +456,76 @@ etc.). - + - R1-R1--7. - The OS machine check and soft reset handlers must be + The OS machine check and soft reset handlers must be able to call the RTAS services: - - + + nvram-fetch - + nvram-store - + check-exception - + display-character - + system-reboot - + set-power-level(0,0) - + power-off - + ibm,set-eeh-option - + ibm,set-slot-reset - + ibm,read-slot-reset-state2 - + - + - R1-R1--8. The stop-self - service need only be serialized with calls to the - stop-self, - start-cpu, and + service need only be serialized with calls to the + stop-self, + start-cpu, and set-power-level services. The OS must be able to call RTAS services on other processors while a processor is stopped or being stopped. - + Software Implementation Notes: - - + + While RTAS must not generate any exceptions, it is still possible that a machine check interrupt may occur during the execution of @@ -535,17 +535,17 @@ It is permissible for the OS exception handler to make an RTAS - call as long as Requirements - and + call as long as Requirements + and are met. In particular, it is - expected that the RTAS + expected that the RTAS check-exception is called from the OS exception handler. - - + +
- +
Resource Allocation and Use During execution, RTAS requires memory for both code and data. This @@ -556,28 +556,28 @@ - R1-R1--1. The OS must allocate “rtas-size” - bytes of contiguous real memory as RTAS + bytes of contiguous real memory as RTAS private data area. This memory must be aligned on a 4096 byte boundary and may not cross a 256 MB boundary. - + - R1-R1--2. The RTAS private data area must not be accessed by the OS. - + - R1-R1--3. Except for the RTAS private data area, the @@ -588,15 +588,15 @@ such modifications are transparent to the OS. - + - R1-R1--4. RTAS calls may not sleep in any fashion nor busy wait for more than a very short period - of time, except for - power-off, ibm,power-off-ups, set-power-level (0,0), + of time, except for + power-off, ibm,power-off-ups, set-power-level (0,0), system-reboot, ibm,update-flash-64-and-reboot, and ibm,os-term. @@ -607,12 +607,12 @@ of microseconds. - + - R1-R1--5. - For RTAS calls which do not allow the + For RTAS calls which do not allow the Status of -2 (Busy), there may be “rare” instances where an anomaly may occur and the call may take longer than a “very short period of time.” In these cases, the call must @@ -623,39 +623,39 @@
- +
Instantiating RTAS RTAS is instantiated by an explicit client interface service call - into OF. The OF device tree contains a property + into OF. The OF device tree contains a property (“rtas-size”, under the /rtas node) which defines how much real memory RTAS - requires from the OS. The OS allocates - “rtas-size” + requires from the OS. The OS allocates + “rtas-size” bytes of real memory, and - then invokes the - instantiate-rtas or + then invokes the + instantiate-rtas or instantiate-rtas-64 method of the /rtas node, passing the real address of the private - data area (or zero, if - “rtas-size” is zero) as the + data area (or zero, if + “rtas-size” is zero) as the rtas-base-address input argument. Firmware binds RTAS to that address, binds the addresses of devices that RTAS uses, performs - any RTAS initialization, and returns the address of the + any RTAS initialization, and returns the address of the rtas-call function that is appropriate. - R1-R1--1. - The instantiate-rtas or + The instantiate-rtas or instantiate-rtas-64 OF method - must have the arguments specified in + must have the arguments specified in . @@ -696,7 +696,7 @@ - Real Address of RTAS area or zero, if + Real Address of RTAS area or zero, if “rtas-size” is zero @@ -718,12 +718,12 @@
- + - R1-R1--2. - The RTAS code bound and initialized by the + The RTAS code bound and initialized by the instantiate-rtas method on a 64-bit capable platform, must be able to handle platform resources that are accessed using 64-bit addresses. @@ -732,26 +732,26 @@
- +
RTAS Device Tree Properties The OF device tree contains a /rtas device node that describes the implemented RTAS features and the output device supported by RTAS. Within this device node are properties that describe the RTAS functions implemented by the - firmware. For every implemented RTAS function, the + firmware. For every implemented RTAS function, the /rtas node contains an OF property whose name is the same as the RTAS function. The value of this property is the token - argument passed into the + argument passed into the rtas-call function when making that specific RTAS call. Note that some - RTAS functions are optional and some are required. This is defined in + RTAS functions are optional and some are required. This is defined in . - R1-R1--1. The OF device tree must contain a device @@ -759,15 +759,15 @@ /rtas which describes the RTAS implementation. - + - R1-R1--2. The /rtas device node must have a property for each - implemented RTAS function in + implemented RTAS function in . The value of this property is - a token that is passed into the + a token that is passed into the rtas-call function to indicate which RTAS function to invoke. @@ -1058,7 +1058,7 @@ - Required for DR operations (see + Required for DR operations (see ) @@ -1334,7 +1334,7 @@ Required for all DR options - See + See . @@ -1380,7 +1380,7 @@ - See + See . @@ -1545,7 +1545,7 @@ - Sometimes (see + Sometimes (see ) @@ -1594,7 +1594,7 @@ - See Requirement + See Requirement . @@ -1611,7 +1611,7 @@ - See Requirement + See Requirement . @@ -1767,19 +1767,19 @@ dynamic reconfiguration is required of the processors. Similarly, a degraded mode may need these, or similar commands in the case of detection of excessive errors. In the case of a processor deconfigured by - dynamic reconfiguration or due to excessive errors, the returned - CPU_status from the + dynamic reconfiguration or due to excessive errors, the returned + CPU_status from the query-cpu-stopped-state RTAS call is 2 (The processor thread is not in the RTAS stopped state) since the deconfigured processor cannot be started. - + - R1-R1--3. - The OF properties listed in + The OF properties listed in must be in the /rtas device tree node prior to booting the OS. @@ -1834,7 +1834,7 @@ The rate, in calls per minute, at which rtas-event-scan - should be called by the OS. See + should be called by the OS. See . @@ -1845,9 +1845,9 @@ - The + The phandle of the device node used by the RTAS - call, + call, display-character. @@ -1866,24 +1866,24 @@ - + - R1-R1--4. All RTAS functions listed as - “Required” in + “Required” in must be implemented in RTAS. - + - R1-R1--5. For the Symmetric Multiprocessor option: The - functions listed as “Required in SMP Platforms” in + functions listed as “Required in SMP Platforms” in must be implemented in RTAS. @@ -1891,8 +1891,8 @@ Software Implementation Notes: - - + + It is permitted for RTAS not to implement those optional functions that are not appropriate or not needed on a particular @@ -1901,14 +1901,14 @@ Vendors may introduce private RTAS calls of their own. If they - do, the property names should be of the form + do, the property names should be of the form “vendor,property” where vendor is a company name string as defined by OF. Future versions of this architecture will not choose RTAS property names that include a comma. - - + +
RTAS Device Tree Properties for Indicators and Sensors @@ -1923,8 +1923,8 @@ (9002), and allocation-state (9003). DR sensors include dr-entity-sense (9003). DR indicators and sensors are required to be there based on the DR entity being supported. Their indices are specified by the DR index - for the DR entity. See - and + for the DR entity. See + and for more information. are static since they represent the base hardware, others are dynamic coming and going with extensions to the base hardware. Indices @@ -1932,50 +1932,50 @@ connector. Information about static non-DR indicators and sensors (like indices and location codes) are specified in the OF device tree at boot time and do not change. Information about non-DR dynamic indicators and - sensors, needs to be gathered via the - ibm,get-indices RTAS call (see + sensors, needs to be gathered via the + ibm,get-indices RTAS call (see ), and sensors, instead of being represented in the device tree. Indicators and sensors within a platform generally have location codes associated with them. Location code information for static indicators and sensors, except DR indicators and sensors, are placed in - the - “<vendor>,indicator-<token>” and + the + “<vendor>,indicator-<token>” and “<vendor>,sensor-<token>” properties, respectively, in the /rtas node, where “<vendor>” is - defined in the column marked “<vendor>” in - and + defined in the column marked “<vendor>” in + and , respectively. Location code information for dynamic indicators and sensors, except DR indicators and - sensors, for the most part come in via the + sensors, for the most part come in via the ibm,get-indices call. Information (index, location code) about a particular indicator or - sensor token, except DR indicators and sensors, are in the - /rtas node properties or are available via the + sensor token, except DR indicators and sensors, are in the + /rtas node properties or are available via the ibm,get-indices call, but not both. When indices are - provided via the - “rtas-sensors” or + provided via the + “rtas-sensors” or “rtas-indicators” properties, it is expected that there exists a sensor/indicator for each index between 0 - and - maxindex. When indices are provided via the + and + maxindex. When indices are provided via the ibm,get-indices call, the indices may not be - contiguous, and any of the indices between 0 and + contiguous, and any of the indices between 0 and maxindex may be missing. - The formats for location codes are defined in + The formats for location codes are defined in . For indicators and sensors, these location codes are for the location of the device being manipulated or measured, not the location of the specific controller or sensor. The location code for an abstracted indicator or sensor is a NULL string. - +
Indicators For static indicators, except DR indicators, OF provides for paired integers ( token maxindex) for each indicator token under the - property + property “rtas-indicators” in the /rtas node. With this information, the OS can @@ -1983,82 +1983,82 @@ maxindex) of each type, that the platform provides. For static indicators, except DR indicators, the extension - property, + property, “<vendor>,indicator-<token>” (see ), provides an array of strings - containing the FRU location codes associated with each indicator. See + containing the FRU location codes associated with each indicator. See . Here, “ <vendor>” corresponds to the - “<vendor>” column of + “<vendor>” column of and “ <token>” corresponds to the token of the - + “rtas-indicators” type. The index of a specific indicator token is used to index into the array - up to + up to maxindex. Indices and location codes for dynamic indicators are obtained via - the + the ibm,get-indices RTAS call and do not appear in the - static properties in the + static properties in the /rtas node. Indices for DR indicators 9001, 9002, and 9003 are obtained from - the DRC index for the DRC connector. See Requirement + the DRC index for the DRC connector. See Requirement . - + - R1-R1--1. For all static indicators, except DR indicators 9001, 9002, and 9003, OF must provide - the extension property, + the extension property, “<vendor>,indicator-<token>”, in the /rtas node, unless the indicator is part of an extension which has its own set of appropriate properties for the indicator, where “ <vendor>” must be as defined in the - column labeled “<vendor>” in + column labeled “<vendor>” in for the specific indicator token value. - + - R1-R1--2. For all static indicators for which - there is an associated + there is an associated “<vendor>,indicator-<token>” property and for which there is not a physical realization, the location code string must be NULL. - + - R1-R1--3. Indices and location codes for any indicator token, except DR indicators 9001, 9002, and 9003, for which the number of such indicators in the platform may change dynamically, must be - obtained via the + obtained via the ibm,get-indices RTAS call and the indicator token - must not appear in the + must not appear in the “<vendor>,indicator-<token>” - or “rtas-indicators” in the + or “rtas-indicators” in the /rtas node. - + - R1-R1--4. The indicator token of 4 must not exist @@ -2066,9 +2066,9 @@ - +
- +
Sensors For static sensors, except DR sensors, OF currently provides for @@ -2080,77 +2080,77 @@ /rtas node. With this information, the OS can determine which types of sensors, and how many of each type, that the platform provides. - For static sensors, except DR sensors, the extension property, + For static sensors, except DR sensors, the extension property, “<vendor>,sensor-<token>” (see ), provides an array of strings - containing the FRU location codes associated with each sensor. See + containing the FRU location codes associated with each sensor. See . Here, “ <vendor>” corresponds to the - “<vendor>” column of + “<vendor>” column of and “ <token>” corresponds to the token in the - + “rtas-sensors” property. The index of a - specific sensor is used to index into the array up to + specific sensor is used to index into the array up to maxindex. Indices and location codes for dynamic sensors, except DR sensors, - are obtained via the + are obtained via the ibm,get-indices RTAS call and do not appear in the - static properties in the + static properties in the /rtas node. Indices for DR sensors 9003 are obtained from the DRC index for the - DRC connector. See Requirement + DRC connector. See Requirement . - + - R1-R1--1. For all static - sensors, except DR sensor 9003, OF must provide the extension property, + sensors, except DR sensor 9003, OF must provide the extension property, “<vendor>,sensor-<token>”, in the /rtas node, unless the sensor is part of an extension which has its own set of appropriate properties for the sensor, where “ <vendor>” must be as defined in the - column labeled “<vendor>” in + column labeled “<vendor>” in for the specific sensor token value. - + - R1-R1--2. For all static sensors for which there - is an associated + is an associated “<vendor>,sensor-<token>” property and for which there is not a physical realization, the location code string must be NULL. - + - R1-R1--3. Indices and location codes for any sensor token, except DR sensor 9003, for which the number of such sensors - in the platform may change dynamically, must be obtained via the + in the platform may change dynamically, must be obtained via the ibm,get-indices RTAS call and the sensor token must - not appear in the + not appear in the “<vendor>,sensor-<token>” - or “rtas-sensors” in the + or “rtas-sensors” in the /rtas node. - + - R1-R1--4. The following sensor tokens must not be @@ -2159,13 +2159,13 @@ - +
- +
- +
Calling Mechanism and Conventions @@ -2178,12 +2178,12 @@ - R1-R1--1. In order to make an RTAS call, the OS must construct an argument call buffer aligned on an eight byte boundary in - physically contiguous real memory as described by + physically contiguous real memory as described by . @@ -2286,51 +2286,51 @@
- + - R1-R1--2. If the system is a 32-bit system, or if RTAS was instantiated by - instantiate-rtas, then all + instantiate-rtas, then all cells in the RTAS argument buffer must be 32-bit sign extended values that are aligned to 4 byte boundaries. - + - R1-R1--3. If the system is - a 64 bit system and if RTAS was instantiated by + a 64 bit system and if RTAS was instantiated by instantiate-rtas-64, then all cells in the RTAS argument buffer must be 64-bit sign extended values that are aligned to 8 byte boundaries. - + - R1-R1--4. RTAS functions must be invoked by branching - to the + to the rtas-call address which is returned by the - + instantiate-rtas or - + instantiate-rtas-64 - OF method (see + OF method (see ). - + - R1-R1--5. Register R3 must contain the argument @@ -2338,24 +2338,24 @@ rtas-call is invoked. - + - R1-R1--6. Register R4 must contain the real address - of the RTAS private data area when - rtas-call is invoked (see Requirement + of the RTAS private data area when + rtas-call is invoked (see Requirement ). - + - R1-R1--7. The Link Register must contain the return - address when + address when rtas-call is invoked. @@ -2363,7 +2363,7 @@ Software Implementation Notes: - + RTAS is not required to perform sanity checking of its input parameters. Using invalid values for any parameter in an RTAS argument @@ -2383,28 +2383,28 @@ addresses or blocks of data which might fall outside of this range. - - + +
- +
Return Codes - R1-R1--1. The first output - value of all the RTAS functions must be a + value of all the RTAS functions must be a Status word which denotes the result of the call. The - - Status word takes on one of the values in + + Status word takes on one of the values in . Non-negative values indicate success. - RTAS + <title>RTAS <emphasis>Status</emphasis> Word Values @@ -2492,7 +2492,7 @@ -9000 - Multi-level isolation error (see + Multi-level isolation error (see ). @@ -2518,7 +2518,7 @@ Additional Positive Numbers - The function succeeded. The meaning of the + The function succeeded. The meaning of the Status word is specific to the RTAS function that was invoked. @@ -2532,15 +2532,15 @@ indicates a summation of all - possible + possible Status word values. A given RTAS function cannot - yield all of the possible - Status words. For the specific + yield all of the possible + Status words. For the specific Status words which apply to a specific RTAS function, see the semantics for that function. Software Implementation Notes: - - + + 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 @@ -2552,9 +2552,9 @@ software delay for 10 raised to the x milliseconds, where x is the last digit of the 990x return code, before calling the function again. - - + + - - - + + + diff --git a/Error Handling/ch_rtas_error_classes.xml b/LoPAR/sec_rtas_error_classes.xml similarity index 88% rename from Error Handling/ch_rtas_error_classes.xml rename to LoPAR/sec_rtas_error_classes.xml index d561d0c..232c37e 100644 --- a/Error Handling/ch_rtas_error_classes.xml +++ b/LoPAR/sec_rtas_error_classes.xml @@ -1,7 +1,7 @@ - - + RTAS Error and Event Classes - + describes the predefined classes of - error and event notifications that can be presented through the - check-exception and + error and event notifications that can be presented through the + check-exception and event-scan RTAS functions. More detailed descriptions - of these classes are given later in this chapter. + of these classes are given later in this chapter. defines nodes in the OF device - tree which, through an + tree which, through an “interrupts” property, may list the platform-dependent interrupts related to each class. From this information, - OSs know which interrupts may be handled by calling + OSs know which interrupts may be handled by calling check-exception. The OF structure for describing these - interrupts is defined in - . + interrupts is defined in + . This document also defines the mask parameter for the - - check-exception and + + check-exception and event-scan RTAS functions which limits the search for errors and events to the classes specified. - +
Error and Event Classes with RTAS Function Call Mask @@ -61,7 +61,7 @@ - OF Node Name(where the + OF Node Name(where the “interrupts” property lists the interrupts) @@ -135,84 +135,84 @@
- + - R1-R1--1. For the Platform Interrupt Event option: The platform must implement the I/O Events and Errors class type along with the - appropriate + appropriate ibm,io-events node property to specify the - interrupts. + interrupts. - + - R1-R1--2. Platform-specific error and event interrupts - that a platform provider wants the OS to enable must be listed in the + that a platform provider wants the OS to enable must be listed in the “interrupts” property of the appropriate OF - event class node, as described in - . + event class node, as described in + . - + - R1-R1--3. To enable platform-specific error and event interrupt notification, OSs must find the - list of interrupts (described in + list of interrupts (described in ) for each error and event class in the OF device tree, and enable them. - + - R1-R1--4. OSs must have interrupt handlers for the - enabled interrupts described in Requirement - , which call the RTAS + enabled interrupts described in Requirement + , which call the RTAS check-exception function to determine the cause of the interrupt. - + - R1-R1--5. Platforms which support error and event reporting must provide information to the OS via - the RTAS - event-scan and + the RTAS + event-scan and check-exception functions, using the reporting format - described in + described in . - + - R1-R1--6. Optional Extended Error Log information, if - returned by the - event-scan or + returned by the + event-scan or check-exception functions, must be in the reporting - format described in + format described in . - + - R1-R1--7. To provide control @@ -223,9 +223,9 @@ extended error log. - + - R1-R1--8. To prevent the loss of any event @@ -234,9 +234,9 @@ of events other than the one being processed. - + - R1-R1--9. Any interrupts or interrupt controls used for @@ -246,48 +246,48 @@ of interrupt by the processing of another. - + - R1-R1--10. If a platform chooses to report multiple event or error sources through a single interrupt, it must ensure that the - interrupt remains asserted or is re-asserted until + interrupt remains asserted or is re-asserted until check-exception has been used to process all outstanding errors or events for that interrupt. - + - + - Platform Implementation Note: In Requirement + Platform Implementation Note: In Requirement , although the fixed-part return format - for - check-exception and + for + check-exception and event-scan is the same, there are some expectations about what types of error response may be returned from these functions, as follows: - - - The + + + The event-scan function is mainly intended to report only errors that have been recovered or are non-critical to the OS, since it is only called on a periodic basis. As such, it should never be used to report a Severity greater than “WARNING”. More critical errors should be signaled by an interrupt. Typically, the expected response of an OS to - an + an event-scan error report is simply to log the error. The check-exception function may report error information of any severity. - + - - If + + If event-scan is reporting a critical error (for example, a checkstop) that occurred before the current boot session, it should not report it with a “FATAL” Severity, even though the condition @@ -297,11 +297,11 @@ RTAS Disposition field for such an error should be “FULLY_RECOVERED”. There is a bit in the extended error log to indicate these “residual” errors. - + - - Although + + Although check-exception can potentially clean up an error and return a “FULLY_RECOVERED” disposition, recovery still may not occur if the MSR @@ -309,13 +309,12 @@ the RI bit, to determine whether processor state is preserved so that a return from the machine check interrupt handler can be safely attempted. - + - - +
diff --git a/Error Handling/sec_rtas_error_indications.xml b/LoPAR/sec_rtas_error_indications.xml similarity index 100% rename from Error Handling/sec_rtas_error_indications.xml rename to LoPAR/sec_rtas_error_indications.xml diff --git a/Error Handling/ch_rtas_error_reporting.xml b/LoPAR/sec_rtas_error_reporting.xml similarity index 91% rename from Error Handling/ch_rtas_error_reporting.xml rename to LoPAR/sec_rtas_error_reporting.xml index f53f0f0..d3e7dca 100644 --- a/Error Handling/ch_rtas_error_reporting.xml +++ b/LoPAR/sec_rtas_error_reporting.xml @@ -1,7 +1,7 @@ - - + RTAS Error and Event Information Reporting - + Architecture Note: All data formats listed in this section are either referenced as byte fields (and therefore are independent of Endian orientation), or an indicator in the data structure describes their Endian @@ -32,5 +32,5 @@ - - + + diff --git a/Error Handling/sec_rtas_error_reporting_introduction.xml b/LoPAR/sec_rtas_error_reporting_introduction.xml similarity index 100% rename from Error Handling/sec_rtas_error_reporting_introduction.xml rename to LoPAR/sec_rtas_error_reporting_introduction.xml diff --git a/Error Handling/sec_rtas_error_reporting_location_codes.xml b/LoPAR/sec_rtas_error_reporting_location_codes.xml similarity index 100% rename from Error Handling/sec_rtas_error_reporting_location_codes.xml rename to LoPAR/sec_rtas_error_reporting_location_codes.xml diff --git a/Error Handling/sec_rtas_error_reporting_return_format.xml b/LoPAR/sec_rtas_error_reporting_return_format.xml similarity index 100% rename from Error Handling/sec_rtas_error_reporting_return_format.xml rename to LoPAR/sec_rtas_error_reporting_return_format.xml diff --git a/LoPAR/sec_rtas_get_dynamic_sensor_state.xml b/LoPAR/sec_rtas_get_dynamic_sensor_state.xml new file mode 100644 index 0000000..aa53f07 --- /dev/null +++ b/LoPAR/sec_rtas_get_dynamic_sensor_state.xml @@ -0,0 +1,288 @@ + + +
+ <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call + This RTAS call behaves as the RTAS + get-sensor-state call, except that the instance of + the sensor is identified by a location code instead of a index. + + + + R1--1. + + Platforms that + implement any sensors that are identified by location code instead of + index (see Requirement + ) must implement the + ibm,get-dynamic-sensor-state RTAS function. + + + + + R1--2. + + The RTAS function + ibm,get-dynamic-sensor-state must implement the + argument call buffer defined by + . +   + + Argument Call Buffer + <emphasis>ibm,get-dynamic-sensor-state</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,get-dynamic-sensor-state + + + + +   + + + + Number Inputs + + + + 2 + + + + +   + + + + Number Outputs + + + + 2 + + + + +   + + + + Sensor + + + + Token defining the sensor + + + + +   + + + + Location Code Address + + + + Real or Logical address of a location code string, in the + format defined by Requirement + + + + + + Out + + + + Status + + + + -1: Hardware error + -2: Busy, try again later + -3: No such indicator + 0: Success + 990x: Extended delay, where x is a number between 0 and + 5, as described below + + + + +   + + + + State + + + + Current state of the sensor as defined in the + Defined Values column of + . + + + + +
+ When 990x + Status is returned, it is suggested that software + delay for 10 raised to the power + x milliseconds (where + x is the last digit of the 990x return code), before + calling + ibm,get-dynamic-sensor-state with the same indicator + type and location code. However, software may call + ibm,get-dynamic-sensor-state again either earlier or + later than this. + + + + + R1--3. + + The OS must not call + ibm,get-dynamic-sensor-state with a different sensor + until a non-busy return + Status has been received from the previous + ibm,get-dynamic-sensor-state call. + + + + + R1--4. + + The work area must be contiguous in real + memory and must reside below 4GB. + + + + + R1--5. + + The input data + format in the work area must be as follows: + + + + 32-bit integer length of the location code string, including + NULL + + + + Location code string, NULL terminated, identifying the sensor to + be set. + + + + + + + R1--6. + + The platform must not modify the location + code string. + + + + + R1--7. + + The OS must only use this call with sensors + which have been provided by the + ibm,get-indices RTAS call with an index value of + 0xFFFFFFFF. + + + + + R1--8. + + The platform must use the + ibm,get-dynamic-sensor-state RTAS call only for + dynamic sensor types of 9004, 9006 and 9007. + + + + + R1--9. + + A Status of -3 must be returned for the following + conditions: + + + + Sensor type not supported + + + + The specified location code does not identify a valid + sensor + + + + + + +
diff --git a/LoPAR/sec_rtas_get_indices.xml b/LoPAR/sec_rtas_get_indices.xml new file mode 100644 index 0000000..e84fbba --- /dev/null +++ b/LoPAR/sec_rtas_get_indices.xml @@ -0,0 +1,455 @@ + + +
+ + <emphasis>ibm,get-indices</emphasis> Call + + The RTAS function + ibm,get-indices is used to obtain the indices and + location codes for a specified indicator or sensor token. It allows for + obtaining the list of indicators and sensors dynamically and therefore + assists in any Dynamic Reconfiguration operation that involves indicators + and sensors being added or deleted from the platform (unlike the + /rtas node + “<vendor>,indicator-<token>”, + “<vendor>,sensor-<token>”, + and “ibm,environmental-sensor” properties). + This call also allows discontiguous indices for a particular indicator or + sensor type (unlike the + “rtas-indicators”, + “rtas-sensors”, and + + “ibm,environmental-sensor” properties). + This RTAS call is not used for DR indicators (9001, 9002, and 9003) + or DR sensors (9003). See the following sections in the DR chapter for more + information: + and + . + It may require several calls to the + ibm,get-indices RTAS routine to get the entire list of + indicators or sensors of a particular type. Each call may specify a + different work area. + The OS may not interleave calls to + ibm,get-indices for different indicator or sensor + types. Other standard RTAS locking rules apply. + + + + R1--1. + + For all DR options: The RTAS function + ibm,get-indices must implement the argument call buffer + defined by + . + + + Argument Call Buffer + <emphasis>ibm,get-indices</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,get-indices + + + + + + Number Inputs + + + + 5 + + + + + + Number Outputs + + + + 2 + + + + + + Indicator or Sensor + + + + 0: indicator of given type + 1: sensor of given type + + + + + + Indicator Type + + + + Indicator or sensor type (for example, 9006, 9007) + + + + + + Work Area Address + + + + Address of work area + + + + + + Work Area Size + + + + Size of work area + + + + + + Starting Number + + + + Integer representing first indicator number to + return + + + + + Out + + + + Status + + + + -1: Hardware error + -3: Indicator type not supported + -4: Optional: Indicator list changed, start again + 0: Success + 1: More data available; call again + 990x:Extended Delay where x is a number 0-5 (see text + below) + + + + + + Next Starting Number + + + + Integer to use as the Starting Number parameter on the next + call, or 1 if no more calls are required + + + + +
+ When the 990x + Status is returned, it is suggested that software delay + for 10 raised to the x milliseconds (where x is the last digit of the 990x + return code), before calling + ibm,get-indices with the same Starting Number and + Indicator Type. However, software may issue the + ibm,get-indices call again either earlier or later than + this. + + + + + R1--2. + + The OS must not interleave calls to + ibm,get-indices for different indicator or sensor + types. + + + + + R1--3. + + On the first call to get a particular + Indicator Type, the caller must provide a Starting + Number of 1 (32-bit integer) + + + + + R1--4. + + When + ibm,get-indices is called with a Starting Number of 1, + firmware must refresh any stale data in previously cached firmware buffers + for that indicator (for example, data made stale by a Dynamic + Reconfiguration operation). + + + + + R1--5. + + When calling + ibm,get-indices with a Starting Number of 1, a + previously returned + Next Starting Number value must be discarded. + + + + + R1--6. + + Optionally, if firmware detects a change in + the indicator list before the entire list is returned, the + ibm,get-indices call must return a -4 and the caller + must start again with a Starting Number of 1. + + + + + R1--7. + + The return data format in the work area for + all sensors and indicators must be as follows: + + + + Number Returned: 32-bit integer representing the number of + indicator indices returned on this call + + + + Sets of (32-bit integer index, 32-bit integer length of location + code including NULLs, location code string (NULL terminated and padded to + nearest 4 byte boundary)), one set per indicator or sensor, with the number + of sets indicated by the first integer in this work buffer + + + + + + + R1--8. + + If the + Status returned is 1 (more data available, call again), + then the caller must call + ibm,get-indices again with the + Starting Number parameter set to the Next Starting + Number integer from the previously returned buffer. + + + + + R1--9. + + The ibm,get-indices RTAS call must return the + Status value of -3 for the following conditions: + + + + Indicator type not supported + + + + No indicators of specified Indicator Type available to + caller + + + + + + + R1--10. + + If the ibm,get-indices RTAS call returns a + Status of anything other than 0 or 1 is returned, the + caller must consider that the contents of the work area is not + defined. + + + + + R1--11. + + The work area specified in the + ibm,get-indices RTAS call argument buffer must be + contiguous in logical real memory and must reside below 4GB. + + + + + R1--12. + + The ibm,get-indices RTAS call must only return the + indicator or sensor indices to which the caller has authorized access at + the time of the call. + + + + + R1--13. + + The ibm,get-indices RTAS call must make no assumptions + about the contents of the work area on the beginning of the call. + + + + + R1--14. + + When the platform supports the + ibm,get-indices RTAS call, the device tree must include + the + “ibm,get-indicator-indices-types” property + in the + /rtas node if the call is to be used for getting + indicator information and must include the + “ibm,get-sensor-indices-types” property in + the + /rtas node if the call is to be used for getting sensor + information. + + + + + R1--15. + + When an indicator token is provided in the + “ibm,get-indicator-indices-types” property, + it must not be included in the + “<vendor>,indicator-<token>” + property and must not be included in the + “rtas-indicators” property. + + + + + R1--16. + + When a sensor token is provided in the + “ibm,get-sensor-indices-types” property, it + must not be included in the + “<vendor>,sensor-<token>” + property and must not be included in the + “rtas-sensors” property. + + + + + R1--17. + + When an environmental sensor token is + provided in the + “ibm,get-sensor-indices-types” property, + users of data in the + “ibm,environmental-sensors” property for + that sensor token must not assume that the indices are contiguous for that + sensor token (that is, any of the indices between 0 and the maxindex, + inclusive, may be missing). + + + + + R1--18. + + When the value of + any index returned is 0xFFFFFFFF, the OS must use the + ibm,get-dynamic-sensor-state and + ibm,set-dynamic-indicator RTAS functions for this + sensor or indicator, using the location code to identify the sensor or + indicator. + + + + + R1--19. + + The OS must not call + get-sensor-state or + get-indicator with an index value of 0xFFFFFFFF. + + + +
diff --git a/LoPAR/sec_rtas_get_vpd.xml b/LoPAR/sec_rtas_get_vpd.xml new file mode 100644 index 0000000..88c575b --- /dev/null +++ b/LoPAR/sec_rtas_get_vpd.xml @@ -0,0 +1,409 @@ + + +
+ <emphasis>ibm,get-vpd</emphasis> RTAS Call + This RTAS call allows for collection of VPD that changes after OS + boot time (after the initial reporting in the OF device tree). When this + call is implemented, there is no overlap between what is reported in the + device tree and what is reported with this RTAS call. Also, when this + RTAS call is implemented, all VPD, except PCI and I/O device VPD, which + is dynamically changed during OS run time is reported with this call and + not via the + “ibm,vpd” property in the OF device + tree. + + + + R1--1. + + For all Dynamic Reconfiguration options + except PCI Hot Plug, when the platform VPD can change dynamically due to + a Dynamic Reconfiguration operation, the platform must implement the + ibm,get-vpd RTAS call. + + + + + R1--2. + + The RTAS function + ibm,get-vpd must implement the argument call buffer + defined by + . + + + Argument Call Buffer + <emphasis>ibm,get-vpd</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,get-vpd + + + + + + Number Inputs + + + + 4 + + + + + + Number Outputs + + + + 3 + + + + + + Pointer to Location Code + + + + Real address of NULL-terminated string, contiguous in + real memory and below 4GB, which is the location code of the + FRU for which to obtain the VPD. When this parameter references + a NULL string the VPD for all location codes is + returned. + + + + + + Work Area Address + + + + Address of work area + + + + + + Work Area Size + + + + Size of work area + + + + + + Sequence Number + + + + Integer representing the sequence number of the call. + First call in sequence starts with 1, following calls (if + necessary) use the + Next Sequence Number returned from the + previous call. + + + + + Out + + + + Status + + + + -1: Hardware error + -3: Parameter error + -4: Optional: VPD changed, start again + 0: Success + 1: More data available; call again + 990x: Extended Delay where x is a number 0-5 (see text + below) + + + + + + Next Sequence Number + + + + Return this integer as the + Sequence Number parameter on the next call + to continue the sequence, or 1 if no more calls are + required + + + + + + Bytes Returned + + + + Integer representing the number of valid bytes returned + in the work area. + + + + +
+ When the 990x + Status is returned, it is suggested that software + delay for 10 raised to the x milliseconds (where x is the last digit of + the 990x return code), before calling + ibm,get-vpd with the same input parameters. However, + software may issue the + ibm,get-vpd call again either earlier or later than + this. + + + + + R1--3. + + On the first call to + ibm,get-vpd for a particular VPD gathering operation, + the caller must provide a + Sequence Number of 1 (32-bit integer) + + + + + R1--4. + + Upon calling + ibm,get-vpd with a + Sequence Number of 1, a previously returned + Next Sequence Number must be discarded. This means + that multiple calls to + ibm,get-vpd cannot be interleaved by multiple + processors, and if processor “B” starts a new + ibm,get-vpd sequence while processor “A” + has a call sequence in process (that is, the function on processor + “A” has returned a + Status of 1, and the subsequent call has not yet been + made) then the call sequence on processor “A” is + abandoned. + + + + + R1--5. + + Optionally, if firmware detects a change in + the VPD being requested before the entire VPD is returned, the + ibm,get-vpd call must return a + Status of -4 and the caller must start again with a + Starting Number of 1. + + Implementation Note: The platform should not impede + forward progress by continuously returning a + Status of -4. + + + + + R1--6. + + The return data format in the work area + must be such that after returning all the data and concatenating all data + together in the order received, that the data is the same as is obtained + from the + “ibm,vpd” property of the OF device + tree. + + + + + R1--7. + + Each stanza of the returned data must + include the YL (location code) keyword. + + + + + R1--8. + + If the + ibm,get-vpd RTAS call is implemented, then the + platform must not provide the + “ibm,vpd” or + “ibm,loc-code” properties in the OF + device tree + root node. + + + + + R1--9. + + If the + ibm,get-vpd RTAS call is implemented, then any VPD + which may change after OS boot must be reported via the + ibm,get-vpd RTAS call. + + + + + R1--10. + + If the + Status returned is 1 (more data available, call + again), then the caller must call + ibm,get-vpd again with the + Sequence Number parameter set to the + Next Sequence Number integer from the previously + returned call. + + + + + R1--11. + + If a + Status of anything other than 0 or 1 is returned, the + contents of the work area is not defined. + + + + + R1--12. + + The work area must be contiguous in real + memory and must reside below 4GB. + + + + + R1--13. + + Firmware cannot count on the contents of + the work area at the beginning of any call to + ibm,get-vpd (regardless of the value of the + Sequence Number). + + + + + R1--14. + + The location code referenced by the + Pointer to Location Code parameter must reside in + contiguous real memory below an address of 4GB. + + + + + R1--15. + + If the + ibm,get-vpd RTAS call is implemented, then firmware + must supply the + “ibm,vpd-size” property in the + /rtas node, the value of which is a single cell, + encoded as with + encode-int, which is the estimated maximum size in + bytes of the VPD that is returned if the + Pointer to Location Code parameter to the + ibm,get-vpd RTAS function is NULL (that is, all + system VPD). This size should take in to account possible concurrent + addition of new platform elements after the partition is started. If + firmware is unable to estimate this size, it may return a value of 0x0 to + indicate that no estimate is available. + + Software Implementation Notes: + + + + + An OS should be prepared for older versions of firmware where + the + “ibm,vpd-size” property is not + provided. + + + + Each stanza of the returned data must include the YL (location + code) keyword. + + + + + + +
diff --git a/Error Handling/sec_rtas_hot_plug.xml b/LoPAR/sec_rtas_hot_plug.xml similarity index 100% rename from Error Handling/sec_rtas_hot_plug.xml rename to LoPAR/sec_rtas_hot_plug.xml diff --git a/RTAS/ch_rtas_introduction.xml b/LoPAR/sec_rtas_introduction.xml similarity index 93% rename from RTAS/ch_rtas_introduction.xml rename to LoPAR/sec_rtas_introduction.xml index c93e06a..735882b 100644 --- a/RTAS/ch_rtas_introduction.xml +++ b/LoPAR/sec_rtas_introduction.xml @@ -1,7 +1,7 @@ - - + xml:id="dbdoclet.50569332_13537"> + Introduction - + The Run-Time Abstraction Service (RTAS) functions are provided by LoPAR platforms to insulate the OS from having to know about and manipulate a number of key platform hardware functions which ordinarily @@ -41,7 +41,7 @@ for a list of all RTAS calls, and which ones are required based on which LoPAR options that are implemented in the platform. - + In order for platforms to achieve this separation of OS code from hardware implementation dependencies, RTAS defines an interface between the platform and the OS that provides control of some of the common devices @@ -54,13 +54,13 @@ different implementations have required much effort and platform-dependent code in the OS. RTAS permits the OS to operate over a much wider range of platforms without specialized code for each platform. - + In general, the OS should not access RTAS resources directly. It should call RTAS to control the resource. - + OS drivers are necessary to provide device specific processing for IOAs. - + The role of RTAS versus OF is very important to understand. OF and RTAS are both platform-specific software, and both are tailored by the platform developer to manipulate the specific platform hardware. However, @@ -69,8 +69,8 @@ whereas OF need not be present when the OS is running. This frees OF’s memory to be used by applications. RTAS is small enough to painlessly coexist with the OS and applications. - + This document uses the term RTAS to refer both to the architected RTAS - interface and to an RTAS implementation. - - + interface and to an RTAS implementation. + + diff --git a/LoPAR/sec_rtas_lpar_perftools.xml b/LoPAR/sec_rtas_lpar_perftools.xml new file mode 100644 index 0000000..4a61fdd --- /dev/null +++ b/LoPAR/sec_rtas_lpar_perftools.xml @@ -0,0 +1,267 @@ + + +
+ <emphasis>ibm,lpar-perftools</emphasis> RTAS Call + + This RTAS call provides access to platform-level facilities for + performance tools running in a partition on an LPAR system. Platforms may + require platform-specific tools, beyond the scope of this architecture, + to make this call available. + + + + R1--1. + + For the Performance Tool Support option: The platform + must implement the LPAR option. + + + + + R1--2. + + For the Performance Tool Support option: RTAS must + implement the + ibm,lpar-perftools call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,lpar-perftools</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,lpar-perftools + + + + + + Number Inputs + + + + 5 + + + + + + Number Outputs + + + + 2 + + + + + + Subfunction + + + + 1: Convert hypervisor IAR value to method name. + + + + + + Work Area Address High + + + + Most significant 32 bits of real address of work + area + + + + + + Work Area Address Low + + + + Least significant 32 bits of real address of work + area + + + + + + Work Area Size + + + + Size of work area in bytes + + + + + + Sequence Number + + + + Integer representing the sequence number of this call. + First call in sequence starts with 1, following calls (if + necessary) use the + Next Sequence Number returned from the + previous call. + + + + + Out + + + + Status + + + + -1: Hardware Error + -2: Busy + -3: Parameter Error (Subfunction invalid, invalid work + area address, invalid work area size) + -9002: Partition does not have authority to perform this + function + -5: Buffer was too small to supply requested data + 0: Success + 990x: Extended delay + + + + + + Next Sequence Number + + + + Return this integer as the + Sequence Number parameter on the next call, + or 1 if no more calls are required. + + + + +
+ When 990x + Status is returned, it is suggested that software + delay for 10 raised to the x milliseconds (where x is the last digit of + the 990x return code), before calling the + ibm,lpar-perftools call with the same input + parameters. However, software may issue the + ibm,lpar-perftools call again earlier or later than + this. + + + + + R1--3. + + For the Performance Tool Support option: For + subfunction value 1, on input the first 8 bytes of + the work area must contain the hypervisor IAR address to be converted. On + output, the first 8 bytes of the work area contain the offset of this + address from the start of the hypervisor function, method or module, + followed by a NULL-terminated text string containing the name of the + hypervisor function, method or module. If the address is not a valid + address in the hypervisor, on output the buffer must contain 0x0 (8 + bytes) followed by a NULL-terminated text string indicating that the + address was not valid. + + + + + R1--4. + + For the Performance Tool support option: The work + area must reside in contiguous memory. + + + + + R1--5. + + For the Performance Tool Support option: If a + Status of anything other than 0 is returned, the + contents of the work area are not defined. + + + + + R1--6. + + For the Performance Tool Support option: A partition + must have at most one call to this function in process at a given time. + This means that if one processor in the partition initiates this call, + receives a Busy or Extended Delay return, and then another processor + calls this function with a sequence number of 1, a subsequent call using + the + Next Sequence Number returned to the first processor + results in a Parameter Error return code. + + + + +
diff --git a/LoPAR/sec_rtas_manage_storage_preservation.xml b/LoPAR/sec_rtas_manage_storage_preservation.xml new file mode 100644 index 0000000..7fac71c --- /dev/null +++ b/LoPAR/sec_rtas_manage_storage_preservation.xml @@ -0,0 +1,262 @@ + + +
+ ibm,manage-storage-preservation + + Platforms may optionally preserve selected regions of storage + (LMBs) across client program boot cycles. + for more information. + + + + R1--1. + + For the Storage Preservation option: The platform + must implement the + ibm,manage-storage-preservation RTAS argument call + buffer as defined by + . + + + <emphasis>ibm,manage-storage-preservation</emphasis> Argument Call + Buffer + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,manage-storage-preservation + + + + + + Number Inputs + + + + 3 + + + + + + Number Outputs + + + + 2 + + + + + + Subfunction + + + + 0 = unused (return -3) + 1 = Register specified LMB for preservation + 2 = Query preservation state of specified LMB + 3 = Deregister for preservation Specific LMB + 4 = Deregister for preservation all caller’s + LMBs. + All other values reserved (return -3) + + + + + + Reg High + + + + The high order 32 bits of the LMB's + “reg” property (Subfunctions + 1-3) + + + + + + Reg Low + + + + The low order 32 bits of the LMB's + “reg” property (Subfunctions + 1-3) + + + + + Out + + + + Status + + + + -1: Hardware error + -2: Busy + -3: Parameter error (Subfunction or Reg invalid; or Reg + for a non-preservable LMB) + 0: Success + 990x: Extended delay where x is a number 0-5 + + + + + + Preservation state + + + + If + Status= Success, the current preservation + state of specified LMB (Subfunctions 1-3) + + + + +
+ + + + + R1--2. + + For the Storage Preservation option: The platform + must include the + “ibm,preservable” property in the + /memory nodes of its OF device tree, containing a + value which reflects the platform's ability to preserve the specific + LMB. + + + + + R1--3. + + For the Storage Preservation option: The value of the + “ibm,preservable” property for the first + LMB must be 0 (cannot be preserved). + + + + + R1--4. + + For the Storage Preservation option: The platform + must not preserve the first LMB, thus must indicate a value of 0 for the + “ibm,preservable” property for the first + LMB. + + + + + R1--5. + + For the Storage Preservation option: The platform + must include the + “ibm,preserved” property in the + /memory nodes of its OF device tree, valued to + reflect the platform's preservation state of the specific LMB. + + + + + R1--6. + + For the Storage Preservation option: The platform, on + a reboot, must include in the OF + /rtas node the + “ibm,preserved-storage” property if the + previous client program registered one or more of its LMBs for + preservation. + + + + + R1--7. + + For the Storage Preservation option: If the client + program registered an LMB for preservation, the platform must preserve + the LMB's storage state across client program reboots. + + + + + R1--8. + + For the Storage Preservation option: The platform, on + a reboot, must include in the OF + /rtas node the + “ibm,request-partition-shutdown” property + which reflects the value of the partition shutdown configuration + variable, and if this property is not present, a value of 0 must be + assumed by the OS. + + + + +
diff --git a/LoPAR/sec_rtas_set_dynamic_indicator.xml b/LoPAR/sec_rtas_set_dynamic_indicator.xml new file mode 100644 index 0000000..23a03ac --- /dev/null +++ b/LoPAR/sec_rtas_set_dynamic_indicator.xml @@ -0,0 +1,278 @@ + + +
+ <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call + + This RTAS call behaves as the RTAS + set-indicator call, except that the instance of the + indicator is identified by a location code instead of a index. + + + + R1--1. + + Platforms that + implement any indicators that are identified by location code instead of + index (see Requirement + ) must implement the + ibm,set-dynamic-indicator RTAS function. + + + + + R1--2. + + The RTAS function + ibm,set-dynamic-indicator must implement the argument + call buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,set-dynamic-indicator</emphasis> + + + + + + + + + Parameter Type + + + + + + Name + + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,set-dynamic-indicator + + + + + + Number Inputs + + + + 3 + + + + + + Number Outputs + + + + 1 + + + + + + Indicator + + + + Token defining the indicator + 9006: Error Log + 9007: Identify Indicator + + + + + + State + + + + Desired new state; see + . + + + + + + Location Code Address + + + + Real or Logical address of a location code string, in the + format defined by Requirement + + + + + + Out + + + + Status + + + + -1: Hardware error + -2: Busy, try again later + -3: No such indicator + 0: Success + 990x: Extended delay, where x is a number between 0 and + 5, as described below + + + + +
+ When 990x + Status is returned, it is suggested that software + delay for 10 raised to the power + x milliseconds (where + x is the last digit of the 990x return code), before + calling + ibm,set-dynamic-indicator with the same indicator + type and location code. However, software may call + ibm,set-dynamic-indicator again either earlier or + later than this. + + + + + R1--3. + + The OS must not call + ibm,set-dynamic-indicator with a different indicator + until a non-busy return + Status has been received from the previous + ibm,set-dynamic-indicator call. + + + + + R1--4. + + The location code string referenced by the + Location Code Address argument in the + ibm,set-dynamic-indicator argument call buffer must + reside in contiguous in real memory below an address of 4GB. + + + + + R1--5. + + The input data + format in the work area must be as follows: + + + + 32-bit integer length of the location code string, including + NULL + + + + Location code string, NULL terminated, identifying the sensor to + be set. + + + + + + + R1--6. + + The platform must not modify the location + code string. + + + + + R1--7. + + The OS must only use this call for + indicators which have been provided by the + ibm,get-indices RTAS call with an index value of + 0xFFFFFFFF. + + + + + R1--8. + + Platforms must identify all indicators + except types 9006 and 9007 by index. + + + + + R1--9. + + The ibm,set-dynamic-indicator RTAS call must return A + Status of -3 for the following conditions: + + + + Indicator type not supported + + + + The specified location code does not identify a valid + indicator + + + + + + +
diff --git a/LoPAR/sec_rtas_suspend_me.xml b/LoPAR/sec_rtas_suspend_me.xml new file mode 100644 index 0000000..5d987f3 --- /dev/null +++ b/LoPAR/sec_rtas_suspend_me.xml @@ -0,0 +1,672 @@ + + +
+ <emphasis>ibm,suspend-me</emphasis> RTAS Call + The + ibm,suspend-me RTAS call provides the calling OS the + ability to suspend processing. Suspension of processing is required as + part of OS hibernation or migration to another platform. This RTAS call + is made by the last active processor thread of a partition. The OS uses + the H_JOIN hcall() (see + ) to deactivate other + processing threads. Processing treads may exit H_JOIN due to an + unmaskable interrupt; if a thread has exited H_JOIN, + ibm,suspend-me fails with a status of “multiple + processor threads active”. The wake up from suspension is triggered + by partition state change (see + sections on "Partition Migration" + and "Partition Hibernation"). The + ibm,suspend-me RTAS call returns only on the calling + virtual processor. Other virtual processors that were inactive when + ibm,suspend-me was called remain so until they are + proded by the OS. + While the logical configuration of a suspended partition remains + static, the physical properties may change; the OS may wish to issue + ibm,update-nodes (see + + ) to determine if any device + tree nodes changed, and then refresh its view of the device + tree physical properties using + ibm,update-properties (see + ) and/or + ibm,configure-connector (see + ). Also during suspension, some + system parameters may have changed. See + , for details. The OS may want + to re-scan selected system parameters. + + + + R1--1. + + For the Partition Suspension option: The platform + must implement the Logical Partitioning option (see + ) + . + + + + + R1--2. + + For the Partition Suspension option: RTAS must + implement the + ibm,suspend-me call within a logical partition using + the argument call buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,suspend-me</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,suspend-me + + + + + + Number Inputs + + + + 0 + + + + + + Number Outputs + + + + 1 + + + + + Out + + + + Status + + + + 9000: Suspension Aborted + 0: Success -- expected return on function resume + -1: Hardware Error +   + -9004: Partition not suspendable + -9005: Multiple processor threads active + -9006: Outstanding COP Operations + + + + +
+ + + + + R1--3. + + For the Partition Suspension option: The + ibm,suspend-me RTAS call must determine that the + calling partition is in the “suspendable state”, else return + a status of -9004 “Partition not suspendable”. + + + + + R1--4. + + For the Partition Suspension option: The + ibm,suspend-me RTAS call must determine that the + calling partition has no other active processor thread, else return a + status of -9005 “Multiple processor threads active”. + + + + + R1--5. + + For the Partition Suspension option: The platform + must implement the Thread Join option (see + ). + + + + + R1--6. + + For the Partition Suspension option: The platform + must restore all partition state as of the time of the call to + ibm,suspend-me prior to returning from the + ibm,suspend-me RTAS call, except for the values of + those Open Firmware Device tree properties as reported using the Update + OF Tree option, and the system parameters given in + . + + + + + R1--7. + + For the Partition Suspension option: The platform + must be prepared to respond to OS requests for updated device tree + information immediately after returning from the + ibm,suspend-me RTAS call. + + + + + R1--8. + + For the Partition Suspension option: The platform + must support the “update OF tree” option. + + + + + R1--9. + + For the Partition Suspension option: The platform + must support the “Partner partition suspended” CRQ Transport + Event (See + ). + + + + + R1--10. + + For the Partition Suspension option: The + ibm,suspend-me RTAS call must cause the platform to + deliver “Partner partition suspended” CRQ Transport Events to + both CRQs of all CRQ connections associated with the partition calling + ibm,suspend-me. + Note: The transport events are visible to the partition calling + ibm,suspend-me after the subsequent resume from + suspension, while the transport events are immediately visible to the + partner partitions of the caller at the time of the suspend. + + + + + R1--11. + + For the Partition Suspension option: The + ibm,suspend-me RTAS call must cause the platform to + set the state of all of the caller’s CRQs to disabled. + + + + + R1--12. + + For the Partition Suspension option: The platform + must implement the H_ENABLE_CRQ hcall() using the syntax and semantics + described in + . + + + + + R1--13. + + For platforms that implement the Partition Suspension and VSCSI + options: The + “compatible” property of the + platform’s + v-scsi and + v-scsi-host nodes must include + “IBM,v-scsi-2” and + “IBM,v-scsi-host-2” respectively + indicating the platform supports the “Partner partition + suspended” CRQ Transport Event. + + + + + R1--14. + + For the Partition Suspension option: If the OS is + participating in OS surveillance, to avoid a surveillance time out, the + OS must disable surveillance (see + ) prior to calling + ibm,suspend-me. + + + + + R1--15. + + For the Partition Suspension option: The platform + must implement the LRDR option (See + ). + + + + + R1--16. + + For the Partition Suspension option: The logical + configuration of a partition, including its view of the + rtas-display-device, and rtas tone facility must not + change while a partition is suspended. + + + + + R1--17. + + For the Partition Suspension option: The platform + must not change the support for a system parameter during + suspension. + + NOTE: If RTAS returns a status of -3 (System + parameter not supported) prior to suspension, it returns a Status of -3 + for accesses to that same system parameter after suspension. Similarly if + RTAS does not return a Status of -3 prior to suspension for a given + system parameter, it does not do so after suspension. + + + + + R1--18. + + For the Partition Suspension option: The platform + must limit the system parameters that change values during suspension to + those specified in + (all system parameters not + specified are preserved). + + + + + R1--19. + + For the Partition Suspension option: The platform + must preserve up to the first 32 SLB entries for each partition processor + during the suspension. Other SLB entries are subject to loss. + + + + + R1--20. + + For the Partition Suspension option with the Platform + Facilities Option: The + ibm,suspend-me RTAS call must determine that the + calling partition has no outstanding coprocessor operations else return a + status of -9005 “Outstanding COP Operations”. + + + System Parameters that May Change During Partition + Migration and Hibernation + + + + + + + + + System Parameter Token + + + + + Name + + + + +   + + + + + + + + 0-15 + + + HMC + + +   + + + + + 18-19 + + + Legacy processor CoD + + +   + + + + + 20 +   + + + SPLPAR characteristics + + + Only specified SPLPAR keywords may change value + + + + +   + + + DesiredEntitledCapacity + + +   + + + + + DesiredMemory + + +   + + + + + DesiredNumberOfProcessors + + +   + + + + + DesiredVariableCapacityWeight + + +   + + + + + DispatchWheelRotationPeriod + + +   + + + + + MinimumEntitledCapacityPerVP + + + Platform prevents migration where current Entitled + Capacity/VCPU ratio would be below the target's minimum. + + + + + MaximumPlatformProcessors + + +   + + + + + 22 + + + platform_auto_power_restart + + +   + + + + + 23 + + + sp-remote-pon + + +   + + + + + 24 + + + sp-rb4-pon + + +   + + + + + 25 + + + sp-snoop-str + + +   + + + + + 30 + + + sp-call-home + + +   + + + + + 31 + + + sp-current-flash-image + + +   + + + + + 33 + + + epow3-quiesce-time + + +   + + + + + 34 + + + memory-preservation-boot-time + + +   + + + + + 35 + + + SCSI initiator identifier + + +   + + + + + 36 + + + AIX support + + + The keyword “support” may not change to the + value “no” for an AIX client. + + + + + 37 + + + enhanced processor CoD + + +   + + + + + 38 + + + enhanced memory CoD + + +   + + + + + 39 + + + CoD Options + + +   + + + + + 41 + + + firmware boot options + + +   + + + + + 43 + + + processor module information + + +   + + + + +
+ + + + +
diff --git a/LoPAR/sec_rtas_update_nodes.xml b/LoPAR/sec_rtas_update_nodes.xml new file mode 100644 index 0000000..343e758 --- /dev/null +++ b/LoPAR/sec_rtas_update_nodes.xml @@ -0,0 +1,829 @@ + + +
+ <emphasis>ibm,update-nodes</emphasis> RTAS Call + + This RTAS call is used to determine which device tree nodes have + changed due to a massive platform reconfiguration such as when the + partition is migrated between machines. Differing platform + reconfigurations are expected to potentially result in different sets of + nodes being updated; the “scope” argument communicates what + set of changes are to be reported. The work area is a 4 KB naturally + aligned area of storage below the first 4 GB; as such, it may not be + large enough to contain the reports of all changed nodes. The status + value of 1 is used to inform the caller that there are more updates to + report and that it will have to call the + ibm,update-nodes RTAS again to receive them. On + subsequent calls the state variable, which is set to zero on the first + call, is set to the value returned on the previous call, to supply RTAS + with the information it needs to continue from where the previous call + ended. + Upon return, the work area contains, in addition to the state + variable, zero or more operation lists, and logically ends with a + terminator (4 byte word naturally aligned containing 0x00000000). An + operation list consists of an operator (4 bytes naturally aligned) and + zero or more (up to a the maximum number of 4 byte locations remaining in + the work area) operands, each 4 bytes long. An operator consists of a + single byte opcode followed by 3 bytes encoded with the binary value of + the number of operands that follow. An operator with an operand length + field of zero performs no operation, and the opcode of zero is reserved + for the terminator -- thus the terminator can be considered a special + encoding of a no-op operator. + + + + The opcode of 0x01 is used for deleted nodes -- the operands are + the + phandle values for the deleted nodes. + + + + The opcode of 0x02 is used for updated nodes -- the operands are + the + phandle values for the updated nodes. The updated + properties are obtained using the + ibm,update-properties RTAS call. + + + + The opcode of 0x03 is used for adding nodes -- the operands are + pairs of + phandle and + drc-index values; the + phandle value denotes the parent node of the node to + be added and the + ibm,drc-index value is passed with the + ibm,configure-connector RTAS call to obtain the + contents of the added node. + + + + To make processing of device tree updates simpler, all opcode 0x01 + (delete) operations (if any) are presented prior to all opcode 0x02 + (update) operations (if any), and finally any 0x03 (addition) operations + are presented. The + phandle operand values are the same + phandle values as reported by the + “ibm,phandle” property. + + + + R1--1. + + For the Update OF Tree option: The platform must + include the + “ibm,phandle” property in all OF nodes + specified in + . + + + + + R1--2. + + For the Update OF Tree option: The platform must + implement the + ibm,update-nodes RTAS call using the argument call + buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,update-nodes</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,update-nodes + + + + + + Number Inputs + + + + 2 + + + + + + Number Outputs + + + + 1 + + + + + + Work Area Address + + + + 32 bit real address of work area + + + + + + Scope + + + + Values per + . + + + + + Out + + + + Status + + + + -1: Hardware Error + -2: Busy + -3: Parameter Error (Purpose does not match the current + partition state) + 0: Success + 1: More nodes updated -- call again + + + + +
+ + + + + R1--3. + + ibm,update-nodes RTAS call work area must be 4 KB + long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else + RTAS may return -3 “Parameter Error”. + + + + + R1--4. + + ibm,update-nodes RTAS for a given value of “ + Scope” must be formatted as specified in + , else RTAS may return -3 + “Parameter Error”. + + + Initial Format of Work Area for + <emphasis>ibm,update-nodes</emphasis> + + + + + + 0x00000000 (State Variable indicates Initial call for + specified + Scope) + + + + + + + 12 bytes of 0x00 (reserved) + + + + + Don’t Care . . . + + + + +
+ + + + + R1--5. + + Upon successful return (non-negative status + value) from + ibm,update-nodes the work area must by formatted as + defined in + . (Note each entry in + is 4 bytes long.) + + + Format of Work Area for + <emphasis>ibm,update-nodes</emphasis> + + + + + + State Variable (4 Bytes) + + + + + 12 bytes of 0x00 (reserved) + + + + + 0 or more operation lists + + + + + . . . + + + + + Terminator (0x00000000) + + + + +
+ + + + + R1--6. + + ibm,update-nodes RTAS call operation list for the + ibm,update-nodes RTAS call must contain an operator + (4 bytes naturally aligned) and zero or more 4 byte operands up to the + end of the work area. + + + + + R1--7. + + An operator in an + ibm,update-nodes RTAS call operation list must be + formatted with, starting at the high order byte, a single byte opcode + followed by 3 bytes encoded with the binary value of the number of + operands that follow. + + + + + R1--8. + + An operator in an + ibm,update-nodes RTAS call operation list with an + operand length field of zero must be considered to perform no + operation. + + + + + R1--9. + + The opcode of 0x01 in an + ibm,update-nodes RTAS call operation list must be + used to denote node deletions. + + + + + R1--10. + + The operands for opcode 0x01 in an + ibm,update-nodes RTAS call operation list must be the + + phandle values for the deleted nodes. + + + + + R1--11. + + The opcode of 0x02 in an + ibm,update-nodes RTAS call operation list must be + used to denote updated nodes. + + + + + R1--12. + + The operands for opcode 0x02 in an + ibm,update-nodes RTAS call operation list must be the + phandle values for the updated nodes that may be used + as the + ibm,update-properties RTAS call argument to obtain + the changed properties of the updated node. + + + + + R1--13. + + The opcode of 0x03 in an + ibm,update-nodes RTAS call operation list must used + for the added nodes. + + + + + R1--14. + + The operands for opcode of 0x03 in an + ibm,update-nodes RTAS call operation list must be + phandle and + drc-index value pairs (each value being 4 bytes + on a natural boundary totalling 8 bytes for the pair) denoting the parent + node of the added node and the + ibm,configure-connector RTAS call argument to obtain + the contents of the added node respectively. + + + + + R1--15. + + All opcode 0x01 (delete) in an + ibm,update-nodes RTAS call operation list (if any) + must be presented prior to any opcode 0x02 (update) operations (if + any). + + + + + R1--16. + + All opcode 0x02 (update) in an + ibm,update-nodes RTAS call operation list (if any) + must be presented prior to any opcode 0x03 (add) operations (if + any). + + + + + R1--17. + + The work area on subsequent call(s) to + ibm,update-nodes RTAS for the same value of the + “Scope” must be formatted as specified in + , else RTAS may return -3 + “Parameter Error”. + + + Format of Work Area for Subsequent Calls to + <emphasis>ibm,update-nodes</emphasis> + + + + + + Value of the 1st 16 bytes of the returned work area from + last call to + ibm,update-nodes RTAS that returned status + of 1. + + + + + + + Don’t Care . . . + + + + +
+ + + + + R1--18. + + The “Scope” argument for the + ibm,update-nodes RTAS call must be one of the values + specified in the scope value column of + , else RTAS may return -3 + “Parameter Error”. + + + + + R1--19. + + For the + ibm,update-nodes RTAS call, the platform must + restrict its reported node updates to those specified in + for the value of the specified + “Scope” argument. + + + + + + R1--20. + + The work area on the first call to + ibm,update-nodes RTAS for a given value of + "Scope" must be formatted as specified in + + else RTAS may return -3 "Parameter Error". + + + Initial Format of Work Area for + <emphasis>ibm,update-nodes</emphasis> with Device Reconfiguration Scope + + + + + + 0x00000000 (State Variable indicates Initial call for specified Scope) + + + + + Unit Address of target device for reconfiguration + + + + + 4 bytes of 0x00 (reserved) + + + + + Don't Care. . . + + + + +
+ + + + + + + Nodes That May be Reported by + <emphasis>ibm,update-nodes</emphasis> for a Given Value of the + “<emphasis>Scope</emphasis>” Argument + + + + + + + + Scope Value + + + Reportable node types (value of + “name” or + “device_type” property) + + + Supported Opcodes + + + + + + + Negative values: Platform Resource Reassignment events as + from + event-scan RTAS + + + cpu + + + 0x02 + + + + + memory + + + 0x02 + + + + + ibm,dynamic-reconfiguration-memory + + + 0x02 + + + + + + ibm,plaform-facilities + + + + 0x01-0x03 + + + + + + ibm,random-v# + + + + 0x01-0x03 + + + + + + ibm,compression-v# + + + + 0x01-0x03 + + + + + + ibm,encryption-v# + + + + 0x01-0x03 + + + + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + + + + 1 Partition Migration / Hibernation + + + + root + + + + 0x02 + + + + + + openprom + + + + 0x02 + + + + + + rtas + + + + 0x02 + + + + + + vdevice + + + + 0x02 + + + + + + cpu + + + + 0x02 + + + + + + cache + + + + 0x01-0x03 + + + + + + options + + + + 0x02 + + + + + + memory + + + + 0x02 + + + + + ibm,dynamic-reconfiguration-memory + + + <all> + + + + + ibm,platform-facilities + + + 0x01-0x03 + + + + + + ibm,random-v# + + + + 0x01-0x03 + + + + + + ibm,compression-v# + + + + 0x01-0x03 + + + + + + ibm,encryption-v# + + + + 0x01-0x03 + + + + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + + + + 2 Activate Firmware + + + + rtas + + + + 0x02 + + + + + 3 Device Reconfiguration + + + + ibm,coherent-platform-facility + + + + 0x02 + + + + + + ibm,coherent-platform-function + + + + 0x02 + + + + +
+ +
diff --git a/LoPAR/sec_rtas_update_properties.xml b/LoPAR/sec_rtas_update_properties.xml new file mode 100644 index 0000000..21e720b --- /dev/null +++ b/LoPAR/sec_rtas_update_properties.xml @@ -0,0 +1,1402 @@ + + +
+ <emphasis>ibm,update-properties</emphasis> RTAS Call + + This RTAS call is used to report updates to the properties changed + due to a massive platform reconfiguration such as when the partition is + migrated between machines. This RTAS call reports changes in the node + specified by the phandle value in the work area passed using the Work + Area Address argument. The phandle value may be that of a critical node + that the caller is interested in or one reported by + ibm,update-nodes RTAS call. These changes may include + any combination of new values, deleted and added properties. Updates for + a given node are retained until the platform is subsequently + reconfigured, and remain available to subsequent calls to + ibm,update-nodes. + There may be more changes than can be reported in a single 4 K work + area. In this case, the RTAS call returns with a status of 1 “More + properties updated -- call again”. On the first call, the second + word of the work area contains the value 0 specifying that the RTAS call + is to start with the first changed property for the specified updated + node. On a call with a status value of 1, the first sixteen (16) bytes of + the work area contain values that, when subsequently supplied in the work + area of another call to + ibm,update-properties RTAS, specify that the call + returns the updated property data for properties after those reported in + the previous call. + A single updated property value string may exceed the capacity of a + single 4 K work area. In that case, the updated property value descriptor + for the property appears in the work area of multiple sequential calls to + ibm,update-properties RTAS. When the updated property + value descriptor contains the final data for the property value, the + property string length field of the updated property value descriptor is + a positive number. When the updated property value descriptor contains + either the initial or interim data for the property value, the updated + property string length field is a negative number denoting the twos + complement of the length of the updated property string contained in the + work area. The data value strings for a given property name are + concatenated until the final updated property value descriptor is + processed. + The first value returned, with an updated property name string of + NULL, is always the node’s name (for example: full path || + name property value || @ unit address) even if there + has been no change. + + + + R1--1. + + For the Update OF Tree option: The platform must + implement the + ibm,update-properties RTAS call using the argument + call buffer defined by + . + + + Argument Call Buffer + <emphasis>ibm,update-properties</emphasis> + + + + + + + + + Parameter Type + + + + + Name + + + + + Values + + + + + + + + In + + + + Token + + + + Token for + ibm,update-properties + + + + + + Number Inputs + + + + 2 + + + + + + Number Outputs + + + + 1 + + + + + + Work Area Address + + + + 32 bit real address of work area + + + + + + Scope + + + + Values per + . + + + + + Out + + + + Status + + + + -1: Hardware Error + -2: Busy + -3: Parameter Error (Purpose does not match the current + partition state) + 0: Success + 1: More properties updated -- call again + + + + +
+ + + + + R1--2. + + ibm,update-properties RTAS call must be 4 KB long + aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS + may return -3 “Parameter Error”. + + + + + R1--3. + + The work area on the first call to + ibm,update-properties RTAS for a given updated node + must be formatted as specified in + , else RTAS may return -3 + “Parameter Error”. + + + Initial Format of Work Area for + <emphasis>ibm,update-properties</emphasis> + + + + + + + phandle of updated node containing updated + properties to be reported (4 bytes) + + + + + + + 0x00000000 (Indicates Initial call for specified + phandle) + + + + + 8 bytes of 0x00 (reserved) + + + + + Don’t Care . . . + + + + +
+ + + + + R1--4. + + Upon successful return (non-negative status + value) from + ibm,update-properties the work area must by formatted + as defined in + . + + + Return Format of Work Area for + <emphasis>ibm,update-properties</emphasis> + + + + + + + + Description + + + + Comments + + + + + + + + phandle of updated node containing updated + properties to be reported. + + + 4 Bytes + + + + + State Variable + (to be returned if status argument value = 1) + + + 4 Bytes + + + + + Reserved + + + 8 bytes + + + + + Number of properties reported in the work area + + + 4 Bytes + The number (N) of updated property value descriptors that + follow -- see below + + + + + N updated property value descriptors + + + Each updated property value descriptor is formatted + as: +   + Null terminated string indicating the name of the updated + property. + followed by: + Value Descriptor -- 4 Bytes decoded as +   + 0x00000000 Name only property ( + “encode-null”) no value + follows +   + 0x80000000 The property is to be deleted no value + follows +   + Other positive values are the length (M) of the + immediately following property value string that completes the + update of the property value. +   + Other negative values are the twos complement of the + length (M) of the immediately following property value string + that either starts or continues the update of the property + value with the remainder in the work area of subsequent call(s) + to + ibm,update-properties. +   + Followed by: + 0-M bytes of property value string. + + + + +
+ + + + + R1--5. + + Upon successful return (non-negative status + value) from + ibm,update-properties when the State Variable had + been 0x00000000, the first updated property descriptor must describe the + fully qualified path name of the node specified by the phandle argument + in the work buffer; the three fields of this updated property descriptor + are: + + + + Property name string is as from + encode-null + + + + Value descriptor is the 4 byte binary length of the value + string + + + + Value string is the fully qualified path name as from the node + name string returned by the open firmware + package-to-path client interface call. + + + + + + + R1--6. + + The work area on subsequent call(s) to + ibm,update-properties RTAS for a given updated node + must be formatted as specified in + , else RTAS may return -3 + “Parameter Error”. + + + Format of Work Area for Subsequent Calls to + <emphasis>ibm,update-properties</emphasis> + + + + + + + phandle of updated node containing updated + properties to be reported (4 Bytes) + + + + + + + Value from last call to + ibm,update-properties RTAS that returned + status of 1 (12 bytes). + + + + + Don’t Care . . . + + + + +
+ + + + + R1--7. + + ibm,update-properties RTAS call, the platform must + restrict its reported property updates to those specified in + for the value of the specified + “Scope” argument. + + + + + R1--8. + + For the + ibm,update-properties RTAS call, the platform must + return a + Status of -3 (Parameter Error) for an unrecognized + value of the “Scope” argument. + + + Properties of the Nodes That May Be Reported by + <emphasis>ibm,update-properties</emphasis> for a “ + <emphasis>Scope</emphasis>” + + + + + + + + Scope Value + + + Reportable node types (value of + “name” or + “device_type” property) + + + Property Name + + + + + + + All negative values: Resource Reassignment events as from + event-scan RTAS + + + /memory + + + “ibm,associativity” + + + + + ibm,dynamic-reconfiguration-memory + + + “ibm,dynamic-memory” + “ibm,dynamic-memory-v2” + + + + + cpu + + + “ibm,associativity” + + + + + + ibm,random-v# + + + + <all> + + + + + + ibm,compression-v# + + + + <all> + + + + + + ibm,encryption-v# + + + + <all> + + + + + + ibm,memory-utilization_instrumentation-v# + + + + <all> + + + + + 1 Partition Migration / Hibernation + + + + root + + + + + “ibm,model-class” + + + + + + + “clock-frequency” + + + + + + + + “ibm,extended-clock-frequency” + + + + + + + “model” + + + + + + + “compatible” + + + + + + + “name” + + + + + + + “system-id” + + + + + + + “ibm,partition-no” + + + + + + + “ibm,drc-info” + + + + + + + “ibm,drc-indexes” + + + + + + + “ibm,drc-names” + + + + + + + “ibm,drc-power-domains” + + + + + + + “ibm,drc-types” + + + + + + + “ibm,aix-diagnostics” + + + + + + + “ibm,diagnostic-lic” + + + + + + + + “ibm,platform-hardware-notification” + + + + + + + + “ibm,ignore-hp-po-fails-for-dlpar” + + + + + + + “ibm,managed-address-types” + + + + + + + “ibm,service-indicator-mode” + + + + + + + openprom + + + + + “model” + + + + + + + rtas + + + + + “power-on-max-latency” + + + + + + + + “ibm,associativity-reference-points” + + + + + + + + “ibm,max-associativity-domains” + + + + + + + “ibm,configure-kernel-dump” + + + + + + + + “ibm,configure-kernel-dump-sizes” + + + + + + + + “ibm,configure-kernel-dump-version” + + + + + + + + “ibm,read-slot-reset-state-functions” + + + + + + + “ibm,configure-pe” + + + + + + + “ibm,change-msix-capable” + + + + + + + “ibm,current-associativity-domains” + + + + + + + vdevice + + + + + “ibm,drc-names” + + + + + + + “ibm,drc-info” + + + + + + children of the + vdevice node + + + + “ibm,loc-code” + + + + + + 1 Partition Migration / Hibernation +   + + + + cpu + + + + + “name” + + + + + + + “d-cache-sets” + + + + + + + “d-cache-size” + + + + + + + “i-cache-sets” + + + + + + + “i-cache-size” + + + + + + + “bus-frequency” + + + + + + + “ibm,extended-bus-frequency” + + + + + + + + “ibm,extended-clock-frequency” + + + + + + + “clock-frequency” + + + + + + + “timebase-frequency” + + + + + + + “l2-cache” + + + + + + + “performance-monitor” + + + + + + + “ibm,associativity” + + + + + + TLB properties (See + ) + + + + + + “slb-size” + + + + + + + “ibm,tbu40-offset” + + + + + + + “ibm,pi-features” + + + + + + + “ibm,spurr” + + + + + + + “ibm,pa-optimizations” + + + + + + + “ibm,dfp” (sign bit + only) + + + + + + “ibm,sub-processors” + + + + + + + cache + + + + + “d-cache-sets” + + + + + + + “d-cache-size” + + + + + + + “i-cache-sets” + + + + + + + “i-cache-size” + + + + + + + l2-cache + + + + + + + options + + + + + “ibm,dasd-spin-interval” + + + + + + + memory + + + + + “ibm,associativity” + + + + + + + ibm,dynamic-reconfiguration-memory + + + + “ibm,associativity-lookup-arrays” + + + + + “ibm,dynamic-memory” + “ibm,dynamic-memory-v2” + only the associativity list index fields + + + + + “ibm,memory-preservation-time” + + + + + + /chosen + + + + + “ibm,architecture-vec-5” + + byte 3 (I/O Super Page Option support parameters) + + + + + 1 Partition Migration / Hibernation +   + + + + ibm,random-v# + + + + <all> + + + + + + ibm,compression-v# + + + + <all> + + + + + + ibm,encryption-v# + + + + <all> + + + + + + ibm,memory-utilization_instrumentation-v# + + + + <all> + + + + + 2 Activate Firmware + + + + rtas + + + + + + Any + /rtas node property as defined per LoPAR + remains invariant. + + + + Any + /rtas node property or definition + extension, except for the value of a function token property*, + may change (provided that the client program has indicated + support for such property or definition extension) including + the following: + + “ibm,read-slot-reset-state-functions” + “ibm,configure-pe” + + + + *NOTE: This exception mandates that if an RTAS function + token property survives a firmware activation, the token value + of that RTAS function call does not change. + + + + + 3 Device Reconfiguration + + + + ibm,coherent-platform-facility + + + + + “compatible” + + + + + + + “status” + + + + + + + “ibm,caia-version” + + + + + + + “ibm,psl-revision” + + + + + + + “ibm,vpd-size” + + + + + + + “vendor-id” + + + + + + + “device-id” + + + + + + + “subsystem-id” + + + + + + + “subsystem-vendor-id” + + + + + + + “revision-id” + + + + + + + “class-code” + + + + + + + ibm,coherent-platform-function + + + + + “compatible” + + + + + + + “reg” + + + + + + + “ibm,max-ints-per-process” + + + + + + + “ibm,min-ints-per-process” + + + + + + + “ibm,#processes” + + + + + + + “ibm,config-record-type” + + + + + + + “ibm,config-record-size” + + + + + + + “ibm,#config-records” + + + + + + + “ibm,error-buffer-size” + + + + + + + “ibm,vpd-size” + + + + + + + “ibm,scratchpad-size” + + + + + + + “vendor-id” + + + + + + + “device-id” + + + + + + + “subsystem-id” + + + + + + + “subsystem-vendor-id” + + + + + + + “revision-id” + + + + + + + “class-code” + + + + + + + “ibm,process-mmio” + + + + + + + “ibm,supports-aur” + + + + + + + “ibm,supports-csrp” + + + + + + + “ibm,supports-prr” + + + + + + + “ibm,process-mmio-size” + + + + + + + “ibm,programming-model” + + + + + + + “ibm,programming-models” + + + + + +
+ + + + + +
diff --git a/RTAS/sec_rtas_get_indices.xml b/RTAS/sec_rtas_get_indices.xml deleted file mode 100644 index e3d0546..0000000 --- a/RTAS/sec_rtas_get_indices.xml +++ /dev/null @@ -1,6374 +0,0 @@ - - -
- - <emphasis>ibm,get-indices</emphasis> Call - - The RTAS function - ibm,get-indices is used to obtain the indices and - location codes for a specified indicator or sensor token. It allows for - obtaining the list of indicators and sensors dynamically and therefore - assists in any Dynamic Reconfiguration operation that involves indicators - and sensors being added or deleted from the platform (unlike the - /rtas node - “<vendor>,indicator-<token>”, - “<vendor>,sensor-<token>”, - and “ibm,environmental-sensor” properties). - This call also allows discontiguous indices for a particular indicator or - sensor type (unlike the - “rtas-indicators”, - “rtas-sensors”, and - - “ibm,environmental-sensor” properties). - This RTAS call is not used for DR indicators (9001, 9002, and 9003) - or DR sensors (9003). See the following sections in the DR chapter for more - information: - and - . - It may require several calls to the - ibm,get-indices RTAS routine to get the entire list of - indicators or sensors of a particular type. Each call may specify a - different work area. - The OS may not interleave calls to - ibm,get-indices for different indicator or sensor - types. Other standard RTAS locking rules apply. - - - - R1--1. - - For all DR options: The RTAS function - ibm,get-indices must implement the argument call buffer - defined by - . - - - Argument Call Buffer - <emphasis>ibm,get-indices</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,get-indices - - - - - - Number Inputs - - - - 5 - - - - - - Number Outputs - - - - 2 - - - - - - Indicator or Sensor - - - - 0: indicator of given type - 1: sensor of given type - - - - - - Indicator Type - - - - Indicator or sensor type (for example, 9006, 9007) - - - - - - Work Area Address - - - - Address of work area - - - - - - Work Area Size - - - - Size of work area - - - - - - Starting Number - - - - Integer representing first indicator number to - return - - - - - Out - - - - Status - - - - -1: Hardware error - -3: Indicator type not supported - -4: Optional: Indicator list changed, start again - 0: Success - 1: More data available; call again - 990x:Extended Delay where x is a number 0-5 (see text - below) - - - - - - Next Starting Number - - - - Integer to use as the Starting Number parameter on the next - call, or 1 if no more calls are required - - - - -
- When the 990x - Status is returned, it is suggested that software delay - for 10 raised to the x milliseconds (where x is the last digit of the 990x - return code), before calling - ibm,get-indices with the same Starting Number and - Indicator Type. However, software may issue the - ibm,get-indices call again either earlier or later than - this. - - - - - R1--2. - - The OS must not interleave calls to - ibm,get-indices for different indicator or sensor - types. - - - - - R1--3. - - On the first call to get a particular - Indicator Type, the caller must provide a Starting - Number of 1 (32-bit integer) - - - - - R1--4. - - When - ibm,get-indices is called with a Starting Number of 1, - firmware must refresh any stale data in previously cached firmware buffers - for that indicator (for example, data made stale by a Dynamic - Reconfiguration operation). - - - - - R1--5. - - When calling - ibm,get-indices with a Starting Number of 1, a - previously returned - Next Starting Number value must be discarded. - - - - - R1--6. - - Optionally, if firmware detects a change in - the indicator list before the entire list is returned, the - ibm,get-indices call must return a -4 and the caller - must start again with a Starting Number of 1. - - - - - R1--7. - - The return data format in the work area for - all sensors and indicators must be as follows: - - - - Number Returned: 32-bit integer representing the number of - indicator indices returned on this call - - - - Sets of (32-bit integer index, 32-bit integer length of location - code including NULLs, location code string (NULL terminated and padded to - nearest 4 byte boundary)), one set per indicator or sensor, with the number - of sets indicated by the first integer in this work buffer - - - - - - - R1--8. - - If the - Status returned is 1 (more data available, call again), - then the caller must call - ibm,get-indices again with the - Starting Number parameter set to the Next Starting - Number integer from the previously returned buffer. - - - - - R1--9. - - The ibm,get-indices RTAS call must return the - Status value of -3 for the following conditions: - - - - Indicator type not supported - - - - No indicators of specified Indicator Type available to - caller - - - - - - - R1--10. - - If the ibm,get-indices RTAS call returns a - Status of anything other than 0 or 1 is returned, the - caller must consider that the contents of the work area is not - defined. - - - - - R1--11. - - The work area specified in the - ibm,get-indices RTAS call argument buffer must be - contiguous in logical real memory and must reside below 4GB. - - - - - R1--12. - - The ibm,get-indices RTAS call must only return the - indicator or sensor indices to which the caller has authorized access at - the time of the call. - - - - - R1--13. - - The ibm,get-indices RTAS call must make no assumptions - about the contents of the work area on the beginning of the call. - - - - - R1--14. - - When the platform supports the - ibm,get-indices RTAS call, the device tree must include - the - “ibm,get-indicator-indices-types” property - in the - /rtas node if the call is to be used for getting - indicator information and must include the - “ibm,get-sensor-indices-types” property in - the - /rtas node if the call is to be used for getting sensor - information. - - - - - R1--15. - - When an indicator token is provided in the - “ibm,get-indicator-indices-types” property, - it must not be included in the - “<vendor>,indicator-<token>” - property and must not be included in the - “rtas-indicators” property. - - - - - R1--16. - - When a sensor token is provided in the - “ibm,get-sensor-indices-types” property, it - must not be included in the - “<vendor>,sensor-<token>” - property and must not be included in the - “rtas-sensors” property. - - - - - R1--17. - - When an environmental sensor token is - provided in the - “ibm,get-sensor-indices-types” property, - users of data in the - “ibm,environmental-sensors” property for - that sensor token must not assume that the indices are contiguous for that - sensor token (that is, any of the indices between 0 and the maxindex, - inclusive, may be missing). - - - - - R1--18. - - When the value of - any index returned is 0xFFFFFFFF, the OS must use the - ibm,get-dynamic-sensor-state and - ibm,set-dynamic-indicator RTAS functions for this - sensor or indicator, using the location code to identify the sensor or - indicator. - - - - - R1--19. - - The OS must not call - get-sensor-state or - get-indicator with an index value of 0xFFFFFFFF. - - - - -
- <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call - - This RTAS call behaves as the RTAS - set-indicator call, except that the instance of the - indicator is identified by a location code instead of a index. - - - - R1--1. - - Platforms that - implement any indicators that are identified by location code instead of - index (see Requirement - ) must implement the - ibm,set-dynamic-indicator RTAS function. - - - - - R1--2. - - The RTAS function - ibm,set-dynamic-indicator must implement the argument - call buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,set-dynamic-indicator</emphasis> - - - - - - - - - Parameter Type - - - - - - Name - - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,set-dynamic-indicator - - - - - - Number Inputs - - - - 3 - - - - - - Number Outputs - - - - 1 - - - - - - Indicator - - - - Token defining the indicator - 9006: Error Log - 9007: Identify Indicator - - - - - - State - - - - Desired new state; see - . - - - - - - Location Code Address - - - - Real or Logical address of a location code string, in the - format defined by Requirement - - - - - - Out - - - - Status - - - - -1: Hardware error - -2: Busy, try again later - -3: No such indicator - 0: Success - 990x: Extended delay, where x is a number between 0 and - 5, as described below - - - - -
- When 990x - Status is returned, it is suggested that software - delay for 10 raised to the power - x milliseconds (where - x is the last digit of the 990x return code), before - calling - ibm,set-dynamic-indicator with the same indicator - type and location code. However, software may call - ibm,set-dynamic-indicator again either earlier or - later than this. - - - - - R1--3. - - The OS must not call - ibm,set-dynamic-indicator with a different indicator - until a non-busy return - Status has been received from the previous - ibm,set-dynamic-indicator call. - - - - - R1--4. - - The location code string referenced by the - Location Code Address argument in the - ibm,set-dynamic-indicator argument call buffer must - reside in contiguous in real memory below an address of 4GB. - - - - - R1--5. - - The input data - format in the work area must be as follows: - - - - 32-bit integer length of the location code string, including - NULL - - - - Location code string, NULL terminated, identifying the sensor to - be set. - - - - - - - R1--6. - - The platform must not modify the location - code string. - - - - - R1--7. - - The OS must only use this call for - indicators which have been provided by the - ibm,get-indices RTAS call with an index value of - 0xFFFFFFFF. - - - - - R1--8. - - Platforms must identify all indicators - except types 9006 and 9007 by index. - - - - - R1--9. - - The ibm,set-dynamic-indicator RTAS call must return A - Status of -3 for the following conditions: - - - - Indicator type not supported - - - - The specified location code does not identify a valid - indicator - - - - - - -
- -
- <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call - This RTAS call behaves as the RTAS - get-sensor-state call, except that the instance of - the sensor is identified by a location code instead of a index. - - - - R1--1. - - Platforms that - implement any sensors that are identified by location code instead of - index (see Requirement - ) must implement the - ibm,get-dynamic-sensor-state RTAS function. - - - - - R1--2. - - The RTAS function - ibm,get-dynamic-sensor-state must implement the - argument call buffer defined by - . -   - - Argument Call Buffer - <emphasis>ibm,get-dynamic-sensor-state</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,get-dynamic-sensor-state - - - - -   - - - - Number Inputs - - - - 2 - - - - -   - - - - Number Outputs - - - - 2 - - - - -   - - - - Sensor - - - - Token defining the sensor - - - - -   - - - - Location Code Address - - - - Real or Logical address of a location code string, in the - format defined by Requirement - - - - - - Out - - - - Status - - - - -1: Hardware error - -2: Busy, try again later - -3: No such indicator - 0: Success - 990x: Extended delay, where x is a number between 0 and - 5, as described below - - - - -   - - - - State - - - - Current state of the sensor as defined in the - Defined Values column of - . - - - - -
- When 990x - Status is returned, it is suggested that software - delay for 10 raised to the power - x milliseconds (where - x is the last digit of the 990x return code), before - calling - ibm,get-dynamic-sensor-state with the same indicator - type and location code. However, software may call - ibm,get-dynamic-sensor-state again either earlier or - later than this. - - - - - R1--3. - - The OS must not call - ibm,get-dynamic-sensor-state with a different sensor - until a non-busy return - Status has been received from the previous - ibm,get-dynamic-sensor-state call. - - - - - R1--4. - - The work area must be contiguous in real - memory and must reside below 4GB. - - - - - R1--5. - - The input data - format in the work area must be as follows: - - - - 32-bit integer length of the location code string, including - NULL - - - - Location code string, NULL terminated, identifying the sensor to - be set. - - - - - - - R1--6. - - The platform must not modify the location - code string. - - - - - R1--7. - - The OS must only use this call with sensors - which have been provided by the - ibm,get-indices RTAS call with an index value of - 0xFFFFFFFF. - - - - - R1--8. - - The platform must use the - ibm,get-dynamic-sensor-state RTAS call only for - dynamic sensor types of 9004, 9006 and 9007. - - - - - R1--9. - - A Status of -3 must be returned for the following - conditions: - - - - Sensor type not supported - - - - The specified location code does not identify a valid - sensor - - - - - - -
- -
- <emphasis>ibm,get-vpd</emphasis> RTAS Call - This RTAS call allows for collection of VPD that changes after OS - boot time (after the initial reporting in the OF device tree). When this - call is implemented, there is no overlap between what is reported in the - device tree and what is reported with this RTAS call. Also, when this - RTAS call is implemented, all VPD, except PCI and I/O device VPD, which - is dynamically changed during OS run time is reported with this call and - not via the - “ibm,vpd” property in the OF device - tree. - - - - R1--1. - - For all Dynamic Reconfiguration options - except PCI Hot Plug, when the platform VPD can change dynamically due to - a Dynamic Reconfiguration operation, the platform must implement the - ibm,get-vpd RTAS call. - - - - - R1--2. - - The RTAS function - ibm,get-vpd must implement the argument call buffer - defined by - . - - - Argument Call Buffer - <emphasis>ibm,get-vpd</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,get-vpd - - - - - - Number Inputs - - - - 4 - - - - - - Number Outputs - - - - 3 - - - - - - Pointer to Location Code - - - - Real address of NULL-terminated string, contiguous in - real memory and below 4GB, which is the location code of the - FRU for which to obtain the VPD. When this parameter references - a NULL string the VPD for all location codes is - returned. - - - - - - Work Area Address - - - - Address of work area - - - - - - Work Area Size - - - - Size of work area - - - - - - Sequence Number - - - - Integer representing the sequence number of the call. - First call in sequence starts with 1, following calls (if - necessary) use the - Next Sequence Number returned from the - previous call. - - - - - Out - - - - Status - - - - -1: Hardware error - -3: Parameter error - -4: Optional: VPD changed, start again - 0: Success - 1: More data available; call again - 990x: Extended Delay where x is a number 0-5 (see text - below) - - - - - - Next Sequence Number - - - - Return this integer as the - Sequence Number parameter on the next call - to continue the sequence, or 1 if no more calls are - required - - - - - - Bytes Returned - - - - Integer representing the number of valid bytes returned - in the work area. - - - - -
- When the 990x - Status is returned, it is suggested that software - delay for 10 raised to the x milliseconds (where x is the last digit of - the 990x return code), before calling - ibm,get-vpd with the same input parameters. However, - software may issue the - ibm,get-vpd call again either earlier or later than - this. - - - - - R1--3. - - On the first call to - ibm,get-vpd for a particular VPD gathering operation, - the caller must provide a - Sequence Number of 1 (32-bit integer) - - - - - R1--4. - - Upon calling - ibm,get-vpd with a - Sequence Number of 1, a previously returned - Next Sequence Number must be discarded. This means - that multiple calls to - ibm,get-vpd cannot be interleaved by multiple - processors, and if processor “B” starts a new - ibm,get-vpd sequence while processor “A” - has a call sequence in process (that is, the function on processor - “A” has returned a - Status of 1, and the subsequent call has not yet been - made) then the call sequence on processor “A” is - abandoned. - - - - - R1--5. - - Optionally, if firmware detects a change in - the VPD being requested before the entire VPD is returned, the - ibm,get-vpd call must return a - Status of -4 and the caller must start again with a - Starting Number of 1. - - Implementation Note: The platform should not impede - forward progress by continuously returning a - Status of -4. - - - - - R1--6. - - The return data format in the work area - must be such that after returning all the data and concatenating all data - together in the order received, that the data is the same as is obtained - from the - “ibm,vpd” property of the OF device - tree. - - - - - R1--7. - - Each stanza of the returned data must - include the YL (location code) keyword. - - - - - R1--8. - - If the - ibm,get-vpd RTAS call is implemented, then the - platform must not provide the - “ibm,vpd” or - “ibm,loc-code” properties in the OF - device tree - root node. - - - - - R1--9. - - If the - ibm,get-vpd RTAS call is implemented, then any VPD - which may change after OS boot must be reported via the - ibm,get-vpd RTAS call. - - - - - R1--10. - - If the - Status returned is 1 (more data available, call - again), then the caller must call - ibm,get-vpd again with the - Sequence Number parameter set to the - Next Sequence Number integer from the previously - returned call. - - - - - R1--11. - - If a - Status of anything other than 0 or 1 is returned, the - contents of the work area is not defined. - - - - - R1--12. - - The work area must be contiguous in real - memory and must reside below 4GB. - - - - - R1--13. - - Firmware cannot count on the contents of - the work area at the beginning of any call to - ibm,get-vpd (regardless of the value of the - Sequence Number). - - - - - R1--14. - - The location code referenced by the - Pointer to Location Code parameter must reside in - contiguous real memory below an address of 4GB. - - - - - R1--15. - - If the - ibm,get-vpd RTAS call is implemented, then firmware - must supply the - “ibm,vpd-size” property in the - /rtas node, the value of which is a single cell, - encoded as with - encode-int, which is the estimated maximum size in - bytes of the VPD that is returned if the - Pointer to Location Code parameter to the - ibm,get-vpd RTAS function is NULL (that is, all - system VPD). This size should take in to account possible concurrent - addition of new platform elements after the partition is started. If - firmware is unable to estimate this size, it may return a value of 0x0 to - indicate that no estimate is available. - - Software Implementation Notes: - - - - - An OS should be prepared for older versions of firmware where - the - “ibm,vpd-size” property is not - provided. - - - - Each stanza of the returned data must include the YL (location - code) keyword. - - - - - - -
- -
- Managing Storage Preservation - - Platforms may optionally preserve selected regions of storage - (LMBs) across client program boot cycles. - for more information. - - - - R1--1. - - For the Storage Preservation option: The platform - must implement the - ibm,manage-storage-preservation RTAS argument call - buffer as defined by - . - - - <emphasis>ibm,manage-storage-preservation</emphasis> Argument Call - Buffer - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,manage-storage-preservation - - - - - - Number Inputs - - - - 3 - - - - - - Number Outputs - - - - 2 - - - - - - Subfunction - - - - 0 = unused (return -3) - 1 = Register specified LMB for preservation - 2 = Query preservation state of specified LMB - 3 = Deregister for preservation Specific LMB - 4 = Deregister for preservation all caller’s - LMBs. - All other values reserved (return -3) - - - - - - Reg High - - - - The high order 32 bits of the LMB's - “reg” property (Subfunctions - 1-3) - - - - - - Reg Low - - - - The low order 32 bits of the LMB's - “reg” property (Subfunctions - 1-3) - - - - - Out - - - - Status - - - - -1: Hardware error - -2: Busy - -3: Parameter error (Subfunction or Reg invalid; or Reg - for a non-preservable LMB) - 0: Success - 990x: Extended delay where x is a number 0-5 - - - - - - Preservation state - - - - If - Status= Success, the current preservation - state of specified LMB (Subfunctions 1-3) - - - - -
- - - - - R1--2. - - For the Storage Preservation option: The platform - must include the - “ibm,preservable” property in the - /memory nodes of its OF device tree, containing a - value which reflects the platform's ability to preserve the specific - LMB. - - - - - R1--3. - - For the Storage Preservation option: The value of the - “ibm,preservable” property for the first - LMB must be 0 (cannot be preserved). - - - - - R1--4. - - For the Storage Preservation option: The platform - must not preserve the first LMB, thus must indicate a value of 0 for the - “ibm,preservable” property for the first - LMB. - - - - - R1--5. - - For the Storage Preservation option: The platform - must include the - “ibm,preserved” property in the - /memory nodes of its OF device tree, valued to - reflect the platform's preservation state of the specific LMB. - - - - - R1--6. - - For the Storage Preservation option: The platform, on - a reboot, must include in the OF - /rtas node the - “ibm,preserved-storage” property if the - previous client program registered one or more of its LMBs for - preservation. - - - - - R1--7. - - For the Storage Preservation option: If the client - program registered an LMB for preservation, the platform must preserve - the LMB's storage state across client program reboots. - - - - - R1--8. - - For the Storage Preservation option: The platform, on - a reboot, must include in the OF - /rtas node the - “ibm,request-partition-shutdown” property - which reflects the value of the partition shutdown configuration - variable, and if this property is not present, a value of 0 must be - assumed by the OS. - - - - -
- -
- <emphasis>ibm,lpar-perftools</emphasis> RTAS Call - - This RTAS call provides access to platform-level facilities for - performance tools running in a partition on an LPAR system. Platforms may - require platform-specific tools, beyond the scope of this architecture, - to make this call available. - - - - R1--1. - - For the Performance Tool Support option: The platform - must implement the LPAR option. - - - - - R1--2. - - For the Performance Tool Support option: RTAS must - implement the - ibm,lpar-perftools call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,lpar-perftools</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,lpar-perftools - - - - - - Number Inputs - - - - 5 - - - - - - Number Outputs - - - - 2 - - - - - - Subfunction - - - - 1: Convert hypervisor IAR value to method name. - - - - - - Work Area Address High - - - - Most significant 32 bits of real address of work - area - - - - - - Work Area Address Low - - - - Least significant 32 bits of real address of work - area - - - - - - Work Area Size - - - - Size of work area in bytes - - - - - - Sequence Number - - - - Integer representing the sequence number of this call. - First call in sequence starts with 1, following calls (if - necessary) use the - Next Sequence Number returned from the - previous call. - - - - - Out - - - - Status - - - - -1: Hardware Error - -2: Busy - -3: Parameter Error (Subfunction invalid, invalid work - area address, invalid work area size) - -9002: Partition does not have authority to perform this - function - -5: Buffer was too small to supply requested data - 0: Success - 990x: Extended delay - - - - - - Next Sequence Number - - - - Return this integer as the - Sequence Number parameter on the next call, - or 1 if no more calls are required. - - - - -
- When 990x - Status is returned, it is suggested that software - delay for 10 raised to the x milliseconds (where x is the last digit of - the 990x return code), before calling the - ibm,lpar-perftools call with the same input - parameters. However, software may issue the - ibm,lpar-perftools call again earlier or later than - this. - - - - - R1--3. - - For the Performance Tool Support option: For - subfunction value 1, on input the first 8 bytes of - the work area must contain the hypervisor IAR address to be converted. On - output, the first 8 bytes of the work area contain the offset of this - address from the start of the hypervisor function, method or module, - followed by a NULL-terminated text string containing the name of the - hypervisor function, method or module. If the address is not a valid - address in the hypervisor, on output the buffer must contain 0x0 (8 - bytes) followed by a NULL-terminated text string indicating that the - address was not valid. - - - - - R1--4. - - For the Performance Tool support option: The work - area must reside in contiguous memory. - - - - - R1--5. - - For the Performance Tool Support option: If a - Status of anything other than 0 is returned, the - contents of the work area are not defined. - - - - - R1--6. - - For the Performance Tool Support option: A partition - must have at most one call to this function in process at a given time. - This means that if one processor in the partition initiates this call, - receives a Busy or Extended Delay return, and then another processor - calls this function with a sequence number of 1, a subsequent call using - the - Next Sequence Number returned to the first processor - results in a Parameter Error return code. - - - - -
- -
- <emphasis>ibm,suspend-me</emphasis> RTAS Call - The - ibm,suspend-me RTAS call provides the calling OS the - ability to suspend processing. Suspension of processing is required as - part of OS hibernation or migration to another platform. This RTAS call - is made by the last active processor thread of a partition. The OS uses - the H_JOIN hcall() (see - ) to deactivate other - processing threads. Processing treads may exit H_JOIN due to an - unmaskable interrupt; if a thread has exited H_JOIN, - ibm,suspend-me fails with a status of “multiple - processor threads active”. The wake up from suspension is triggered - by partition state change (see - sections on "Partition Migration" - and "Partition Hibernation"). The - ibm,suspend-me RTAS call returns only on the calling - virtual processor. Other virtual processors that were inactive when - ibm,suspend-me was called remain so until they are - proded by the OS. - While the logical configuration of a suspended partition remains - static, the physical properties may change; the OS may wish to issue - ibm,update-nodes (see - - ) to determine if any device - tree nodes changed, and then refresh its view of the device - tree physical properties using - ibm,update-properties (see - ) and/or - ibm,configure-connector (see - ). Also during suspension, some - system parameters may have changed. See - , for details. The OS may want - to re-scan selected system parameters. - - - - R1--1. - - For the Partition Suspension option: The platform - must implement the Logical Partitioning option (see - ) - . - - - - - R1--2. - - For the Partition Suspension option: RTAS must - implement the - ibm,suspend-me call within a logical partition using - the argument call buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,suspend-me</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,suspend-me - - - - - - Number Inputs - - - - 0 - - - - - - Number Outputs - - - - 1 - - - - - Out - - - - Status - - - - 9000: Suspension Aborted - 0: Success -- expected return on function resume - -1: Hardware Error -   - -9004: Partition not suspendable - -9005: Multiple processor threads active - -9006: Outstanding COP Operations - - - - -
- - - - - R1--3. - - For the Partition Suspension option: The - ibm,suspend-me RTAS call must determine that the - calling partition is in the “suspendable state”, else return - a status of -9004 “Partition not suspendable”. - - - - - R1--4. - - For the Partition Suspension option: The - ibm,suspend-me RTAS call must determine that the - calling partition has no other active processor thread, else return a - status of -9005 “Multiple processor threads active”. - - - - - R1--5. - - For the Partition Suspension option: The platform - must implement the Thread Join option (see - ). - - - - - R1--6. - - For the Partition Suspension option: The platform - must restore all partition state as of the time of the call to - ibm,suspend-me prior to returning from the - ibm,suspend-me RTAS call, except for the values of - those Open Firmware Device tree properties as reported using the Update - OF Tree option, and the system parameters given in - . - - - - - R1--7. - - For the Partition Suspension option: The platform - must be prepared to respond to OS requests for updated device tree - information immediately after returning from the - ibm,suspend-me RTAS call. - - - - - R1--8. - - For the Partition Suspension option: The platform - must support the “update OF tree” option. - - - - - R1--9. - - For the Partition Suspension option: The platform - must support the “Partner partition suspended” CRQ Transport - Event (See - ). - - - - - R1--10. - - For the Partition Suspension option: The - ibm,suspend-me RTAS call must cause the platform to - deliver “Partner partition suspended” CRQ Transport Events to - both CRQs of all CRQ connections associated with the partition calling - ibm,suspend-me. - Note: The transport events are visible to the partition calling - ibm,suspend-me after the subsequent resume from - suspension, while the transport events are immediately visible to the - partner partitions of the caller at the time of the suspend. - - - - - R1--11. - - For the Partition Suspension option: The - ibm,suspend-me RTAS call must cause the platform to - set the state of all of the caller’s CRQs to disabled. - - - - - R1--12. - - For the Partition Suspension option: The platform - must implement the H_ENABLE_CRQ hcall() using the syntax and semantics - described in - . - - - - - R1--13. - - For platforms that implement the Partition Suspension and VSCSI - options: The - “compatible” property of the - platform’s - v-scsi and - v-scsi-host nodes must include - “IBM,v-scsi-2” and - “IBM,v-scsi-host-2” respectively - indicating the platform supports the “Partner partition - suspended” CRQ Transport Event. - - - - - R1--14. - - For the Partition Suspension option: If the OS is - participating in OS surveillance, to avoid a surveillance time out, the - OS must disable surveillance (see - ) prior to calling - ibm,suspend-me. - - - - - R1--15. - - For the Partition Suspension option: The platform - must implement the LRDR option (See - ). - - - - - R1--16. - - For the Partition Suspension option: The logical - configuration of a partition, including its view of the - rtas-display-device, and rtas tone facility must not - change while a partition is suspended. - - - - - R1--17. - - For the Partition Suspension option: The platform - must not change the support for a system parameter during - suspension. - - NOTE: If RTAS returns a status of -3 (System - parameter not supported) prior to suspension, it returns a Status of -3 - for accesses to that same system parameter after suspension. Similarly if - RTAS does not return a Status of -3 prior to suspension for a given - system parameter, it does not do so after suspension. - - - - - R1--18. - - For the Partition Suspension option: The platform - must limit the system parameters that change values during suspension to - those specified in - (all system parameters not - specified are preserved). - - - - - R1--19. - - For the Partition Suspension option: The platform - must preserve up to the first 32 SLB entries for each partition processor - during the suspension. Other SLB entries are subject to loss. - - - - - R1--20. - - For the Partition Suspension option with the Platform - Facilities Option: The - ibm,suspend-me RTAS call must determine that the - calling partition has no outstanding coprocessor operations else return a - status of -9005 “Outstanding COP Operations”. - - - System Parameters that May Change During Partition - Migration and Hibernation - - - - - - - - - System Parameter Token - - - - - Name - - - - -   - - - - - - - - 0-15 - - - HMC - - -   - - - - - 18-19 - - - Legacy processor CoD - - -   - - - - - 20 -   - - - SPLPAR characteristics - - - Only specified SPLPAR keywords may change value - - - - -   - - - DesiredEntitledCapacity - - -   - - - - - DesiredMemory - - -   - - - - - DesiredNumberOfProcessors - - -   - - - - - DesiredVariableCapacityWeight - - -   - - - - - DispatchWheelRotationPeriod - - -   - - - - - MinimumEntitledCapacityPerVP - - - Platform prevents migration where current Entitled - Capacity/VCPU ratio would be below the target's minimum. - - - - - MaximumPlatformProcessors - - -   - - - - - 22 - - - platform_auto_power_restart - - -   - - - - - 23 - - - sp-remote-pon - - -   - - - - - 24 - - - sp-rb4-pon - - -   - - - - - 25 - - - sp-snoop-str - - -   - - - - - 30 - - - sp-call-home - - -   - - - - - 31 - - - sp-current-flash-image - - -   - - - - - 33 - - - epow3-quiesce-time - - -   - - - - - 34 - - - memory-preservation-boot-time - - -   - - - - - 35 - - - SCSI initiator identifier - - -   - - - - - 36 - - - AIX support - - - The keyword “support” may not change to the - value “no” for an AIX client. - - - - - 37 - - - enhanced processor CoD - - -   - - - - - 38 - - - enhanced memory CoD - - -   - - - - - 39 - - - CoD Options - - -   - - - - - 41 - - - firmware boot options - - -   - - - - - 43 - - - processor module information - - -   - - - - -
- - - - -
- -
- <emphasis>ibm,update-nodes</emphasis> RTAS Call - - This RTAS call is used to determine which device tree nodes have - changed due to a massive platform reconfiguration such as when the - partition is migrated between machines. Differing platform - reconfigurations are expected to potentially result in different sets of - nodes being updated; the “scope” argument communicates what - set of changes are to be reported. The work area is a 4 KB naturally - aligned area of storage below the first 4 GB; as such, it may not be - large enough to contain the reports of all changed nodes. The status - value of 1 is used to inform the caller that there are more updates to - report and that it will have to call the - ibm,update-nodes RTAS again to receive them. On - subsequent calls the state variable, which is set to zero on the first - call, is set to the value returned on the previous call, to supply RTAS - with the information it needs to continue from where the previous call - ended. - Upon return, the work area contains, in addition to the state - variable, zero or more operation lists, and logically ends with a - terminator (4 byte word naturally aligned containing 0x00000000). An - operation list consists of an operator (4 bytes naturally aligned) and - zero or more (up to a the maximum number of 4 byte locations remaining in - the work area) operands, each 4 bytes long. An operator consists of a - single byte opcode followed by 3 bytes encoded with the binary value of - the number of operands that follow. An operator with an operand length - field of zero performs no operation, and the opcode of zero is reserved - for the terminator -- thus the terminator can be considered a special - encoding of a no-op operator. - - - - The opcode of 0x01 is used for deleted nodes -- the operands are - the - phandle values for the deleted nodes. - - - - The opcode of 0x02 is used for updated nodes -- the operands are - the - phandle values for the updated nodes. The updated - properties are obtained using the - ibm,update-properties RTAS call. - - - - The opcode of 0x03 is used for adding nodes -- the operands are - pairs of - phandle and - drc-index values; the - phandle value denotes the parent node of the node to - be added and the - ibm,drc-index value is passed with the - ibm,configure-connector RTAS call to obtain the - contents of the added node. - - - - To make processing of device tree updates simpler, all opcode 0x01 - (delete) operations (if any) are presented prior to all opcode 0x02 - (update) operations (if any), and finally any 0x03 (addition) operations - are presented. The - phandle operand values are the same - phandle values as reported by the - “ibm,phandle” property. - - - - R1--1. - - For the Update OF Tree option: The platform must - include the - “ibm,phandle” property in all OF nodes - specified in - . - - - - - R1--2. - - For the Update OF Tree option: The platform must - implement the - ibm,update-nodes RTAS call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,update-nodes</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,update-nodes - - - - - - Number Inputs - - - - 2 - - - - - - Number Outputs - - - - 1 - - - - - - Work Area Address - - - - 32 bit real address of work area - - - - - - Scope - - - - Values per - . - - - - - Out - - - - Status - - - - -1: Hardware Error - -2: Busy - -3: Parameter Error (Purpose does not match the current - partition state) - 0: Success - 1: More nodes updated -- call again - - - - -
- - - - - R1--3. - - ibm,update-nodes RTAS call work area must be 4 KB - long aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else - RTAS may return -3 “Parameter Error”. - - - - - R1--4. - - ibm,update-nodes RTAS for a given value of “ - Scope” must be formatted as specified in - , else RTAS may return -3 - “Parameter Error”. - - - Initial Format of Work Area for - <emphasis>ibm,update-nodes</emphasis> - - - - - - 0x00000000 (State Variable indicates Initial call for - specified - Scope) - - - - - - - 12 bytes of 0x00 (reserved) - - - - - Don’t Care . . . - - - - -
- - - - - R1--5. - - Upon successful return (non-negative status - value) from - ibm,update-nodes the work area must by formatted as - defined in - . (Note each entry in - is 4 bytes long.) - - - Format of Work Area for - <emphasis>ibm,update-nodes</emphasis> - - - - - - State Variable (4 Bytes) - - - - - 12 bytes of 0x00 (reserved) - - - - - 0 or more operation lists - - - - - . . . - - - - - Terminator (0x00000000) - - - - -
- - - - - R1--6. - - ibm,update-nodes RTAS call operation list for the - ibm,update-nodes RTAS call must contain an operator - (4 bytes naturally aligned) and zero or more 4 byte operands up to the - end of the work area. - - - - - R1--7. - - An operator in an - ibm,update-nodes RTAS call operation list must be - formatted with, starting at the high order byte, a single byte opcode - followed by 3 bytes encoded with the binary value of the number of - operands that follow. - - - - - R1--8. - - An operator in an - ibm,update-nodes RTAS call operation list with an - operand length field of zero must be considered to perform no - operation. - - - - - R1--9. - - The opcode of 0x01 in an - ibm,update-nodes RTAS call operation list must be - used to denote node deletions. - - - - - R1--10. - - The operands for opcode 0x01 in an - ibm,update-nodes RTAS call operation list must be the - - phandle values for the deleted nodes. - - - - - R1--11. - - The opcode of 0x02 in an - ibm,update-nodes RTAS call operation list must be - used to denote updated nodes. - - - - - R1--12. - - The operands for opcode 0x02 in an - ibm,update-nodes RTAS call operation list must be the - phandle values for the updated nodes that may be used - as the - ibm,update-properties RTAS call argument to obtain - the changed properties of the updated node. - - - - - R1--13. - - The opcode of 0x03 in an - ibm,update-nodes RTAS call operation list must used - for the added nodes. - - - - - R1--14. - - The operands for opcode of 0x03 in an - ibm,update-nodes RTAS call operation list must be - phandle and - drc-index value pairs (each value being 4 bytes - on a natural boundary totalling 8 bytes for the pair) denoting the parent - node of the added node and the - ibm,configure-connector RTAS call argument to obtain - the contents of the added node respectively. - - - - - R1--15. - - All opcode 0x01 (delete) in an - ibm,update-nodes RTAS call operation list (if any) - must be presented prior to any opcode 0x02 (update) operations (if - any). - - - - - R1--16. - - All opcode 0x02 (update) in an - ibm,update-nodes RTAS call operation list (if any) - must be presented prior to any opcode 0x03 (add) operations (if - any). - - - - - R1--17. - - The work area on subsequent call(s) to - ibm,update-nodes RTAS for the same value of the - “Scope” must be formatted as specified in - , else RTAS may return -3 - “Parameter Error”. - - - Format of Work Area for Subsequent Calls to - <emphasis>ibm,update-nodes</emphasis> - - - - - - Value of the 1st 16 bytes of the returned work area from - last call to - ibm,update-nodes RTAS that returned status - of 1. - - - - - - - Don’t Care . . . - - - - -
- - - - - R1--18. - - The “Scope” argument for the - ibm,update-nodes RTAS call must be one of the values - specified in the scope value column of - , else RTAS may return -3 - “Parameter Error”. - - - - - R1--19. - - For the - ibm,update-nodes RTAS call, the platform must - restrict its reported node updates to those specified in - for the value of the specified - “Scope” argument. - - - - - - R1--20. - - The work area on the first call to - ibm,update-nodes RTAS for a given value of - "Scope" must be formatted as specified in - - else RTAS may return -3 "Parameter Error". - - - Initial Format of Work Area for - <emphasis>ibm,update-nodes</emphasis> with Device Reconfiguration Scope - - - - - - 0x00000000 (State Variable indicates Initial call for specified Scope) - - - - - Unit Address of target device for reconfiguration - - - - - 4 bytes of 0x00 (reserved) - - - - - Don't Care. . . - - - - -
- - - - - - - Nodes That May be Reported by - <emphasis>ibm,update-nodes</emphasis> for a Given Value of the - “<emphasis>Scope</emphasis>” Argument - - - - - - - - Scope Value - - - Reportable node types (value of - “name” or - “device_type” property) - - - Supported Opcodes - - - - - - - Negative values: Platform Resource Reassignment events as - from - event-scan RTAS - - - cpu - - - 0x02 - - - - - memory - - - 0x02 - - - - - ibm,dynamic-reconfiguration-memory - - - 0x02 - - - - - - ibm,plaform-facilities - - - - 0x01-0x03 - - - - - - ibm,random-v# - - - - 0x01-0x03 - - - - - - ibm,compression-v# - - - - 0x01-0x03 - - - - - - ibm,encryption-v# - - - - 0x01-0x03 - - - - - - ibm,memory-utilization_instrumentation-v# - - - - 0x01-0x03 - - - - - 1 Partition Migration / Hibernation - - - - root - - - - 0x02 - - - - - - openprom - - - - 0x02 - - - - - - rtas - - - - 0x02 - - - - - - vdevice - - - - 0x02 - - - - - - cpu - - - - 0x02 - - - - - - cache - - - - 0x01-0x03 - - - - - - options - - - - 0x02 - - - - - - memory - - - - 0x02 - - - - - ibm,dynamic-reconfiguration-memory - - - <all> - - - - - ibm,platform-facilities - - - 0x01-0x03 - - - - - - ibm,random-v# - - - - 0x01-0x03 - - - - - - ibm,compression-v# - - - - 0x01-0x03 - - - - - - ibm,encryption-v# - - - - 0x01-0x03 - - - - - - ibm,memory-utilization_instrumentation-v# - - - - 0x01-0x03 - - - - - 2 Activate Firmware - - - - rtas - - - - 0x02 - - - - - 3 Device Reconfiguration - - - - ibm,coherent-platform-facility - - - - 0x02 - - - - - - ibm,coherent-platform-function - - - - 0x02 - - - - -
- -
- -
- <emphasis>ibm,update-properties</emphasis> RTAS Call - - This RTAS call is used to report updates to the properties changed - due to a massive platform reconfiguration such as when the partition is - migrated between machines. This RTAS call reports changes in the node - specified by the phandle value in the work area passed using the Work - Area Address argument. The phandle value may be that of a critical node - that the caller is interested in or one reported by - ibm,update-nodes RTAS call. These changes may include - any combination of new values, deleted and added properties. Updates for - a given node are retained until the platform is subsequently - reconfigured, and remain available to subsequent calls to - ibm,update-nodes. - There may be more changes than can be reported in a single 4 K work - area. In this case, the RTAS call returns with a status of 1 “More - properties updated -- call again”. On the first call, the second - word of the work area contains the value 0 specifying that the RTAS call - is to start with the first changed property for the specified updated - node. On a call with a status value of 1, the first sixteen (16) bytes of - the work area contain values that, when subsequently supplied in the work - area of another call to - ibm,update-properties RTAS, specify that the call - returns the updated property data for properties after those reported in - the previous call. - A single updated property value string may exceed the capacity of a - single 4 K work area. In that case, the updated property value descriptor - for the property appears in the work area of multiple sequential calls to - ibm,update-properties RTAS. When the updated property - value descriptor contains the final data for the property value, the - property string length field of the updated property value descriptor is - a positive number. When the updated property value descriptor contains - either the initial or interim data for the property value, the updated - property string length field is a negative number denoting the twos - complement of the length of the updated property string contained in the - work area. The data value strings for a given property name are - concatenated until the final updated property value descriptor is - processed. - The first value returned, with an updated property name string of - NULL, is always the node’s name (for example: full path || - name property value || @ unit address) even if there - has been no change. - - - - R1--1. - - For the Update OF Tree option: The platform must - implement the - ibm,update-properties RTAS call using the argument - call buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,update-properties</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,update-properties - - - - - - Number Inputs - - - - 2 - - - - - - Number Outputs - - - - 1 - - - - - - Work Area Address - - - - 32 bit real address of work area - - - - - - Scope - - - - Values per - . - - - - - Out - - - - Status - - - - -1: Hardware Error - -2: Busy - -3: Parameter Error (Purpose does not match the current - partition state) - 0: Success - 1: More properties updated -- call again - - - - -
- - - - - R1--2. - - ibm,update-properties RTAS call must be 4 KB long - aligned on a 4 KB boundary that is accessible with MSR[DR] = 0, else RTAS - may return -3 “Parameter Error”. - - - - - R1--3. - - The work area on the first call to - ibm,update-properties RTAS for a given updated node - must be formatted as specified in - , else RTAS may return -3 - “Parameter Error”. - - - Initial Format of Work Area for - <emphasis>ibm,update-properties</emphasis> - - - - - - - phandle of updated node containing updated - properties to be reported (4 bytes) - - - - - - - 0x00000000 (Indicates Initial call for specified - phandle) - - - - - 8 bytes of 0x00 (reserved) - - - - - Don’t Care . . . - - - - -
- - - - - R1--4. - - Upon successful return (non-negative status - value) from - ibm,update-properties the work area must by formatted - as defined in - . - - - Return Format of Work Area for - <emphasis>ibm,update-properties</emphasis> - - - - - - - - Description - - - - Comments - - - - - - - - phandle of updated node containing updated - properties to be reported. - - - 4 Bytes - - - - - State Variable - (to be returned if status argument value = 1) - - - 4 Bytes - - - - - Reserved - - - 8 bytes - - - - - Number of properties reported in the work area - - - 4 Bytes - The number (N) of updated property value descriptors that - follow -- see below - - - - - N updated property value descriptors - - - Each updated property value descriptor is formatted - as: -   - Null terminated string indicating the name of the updated - property. - followed by: - Value Descriptor -- 4 Bytes decoded as -   - 0x00000000 Name only property ( - “encode-null”) no value - follows -   - 0x80000000 The property is to be deleted no value - follows -   - Other positive values are the length (M) of the - immediately following property value string that completes the - update of the property value. -   - Other negative values are the twos complement of the - length (M) of the immediately following property value string - that either starts or continues the update of the property - value with the remainder in the work area of subsequent call(s) - to - ibm,update-properties. -   - Followed by: - 0-M bytes of property value string. - - - - -
- - - - - R1--5. - - Upon successful return (non-negative status - value) from - ibm,update-properties when the State Variable had - been 0x00000000, the first updated property descriptor must describe the - fully qualified path name of the node specified by the phandle argument - in the work buffer; the three fields of this updated property descriptor - are: - - - - Property name string is as from - encode-null - - - - Value descriptor is the 4 byte binary length of the value - string - - - - Value string is the fully qualified path name as from the node - name string returned by the open firmware - package-to-path client interface call. - - - - - - - R1--6. - - The work area on subsequent call(s) to - ibm,update-properties RTAS for a given updated node - must be formatted as specified in - , else RTAS may return -3 - “Parameter Error”. - - - Format of Work Area for Subsequent Calls to - <emphasis>ibm,update-properties</emphasis> - - - - - - - phandle of updated node containing updated - properties to be reported (4 Bytes) - - - - - - - Value from last call to - ibm,update-properties RTAS that returned - status of 1 (12 bytes). - - - - - Don’t Care . . . - - - - -
- - - - - R1--7. - - ibm,update-properties RTAS call, the platform must - restrict its reported property updates to those specified in - for the value of the specified - “Scope” argument. - - - - - R1--8. - - For the - ibm,update-properties RTAS call, the platform must - return a - Status of -3 (Parameter Error) for an unrecognized - value of the “Scope” argument. - - - Properties of the Nodes That May Be Reported by - <emphasis>ibm,update-properties</emphasis> for a “ - <emphasis>Scope</emphasis>” - - - - - - - - Scope Value - - - Reportable node types (value of - “name” or - “device_type” property) - - - Property Name - - - - - - - All negative values: Resource Reassignment events as from - event-scan RTAS - - - /memory - - - “ibm,associativity” - - - - - ibm,dynamic-reconfiguration-memory - - - “ibm,dynamic-memory” - “ibm,dynamic-memory-v2” - - - - - cpu - - - “ibm,associativity” - - - - - - ibm,random-v# - - - - <all> - - - - - - ibm,compression-v# - - - - <all> - - - - - - ibm,encryption-v# - - - - <all> - - - - - - ibm,memory-utilization_instrumentation-v# - - - - <all> - - - - - 1 Partition Migration / Hibernation - - - - root - - - - - “ibm,model-class” - - - - - - - “clock-frequency” - - - - - - - - “ibm,extended-clock-frequency” - - - - - - - “model” - - - - - - - “compatible” - - - - - - - “name” - - - - - - - “system-id” - - - - - - - “ibm,partition-no” - - - - - - - “ibm,drc-info” - - - - - - - “ibm,drc-indexes” - - - - - - - “ibm,drc-names” - - - - - - - “ibm,drc-power-domains” - - - - - - - “ibm,drc-types” - - - - - - - “ibm,aix-diagnostics” - - - - - - - “ibm,diagnostic-lic” - - - - - - - - “ibm,platform-hardware-notification” - - - - - - - - “ibm,ignore-hp-po-fails-for-dlpar” - - - - - - - “ibm,managed-address-types” - - - - - - - “ibm,service-indicator-mode” - - - - - - - openprom - - - - - “model” - - - - - - - rtas - - - - - “power-on-max-latency” - - - - - - - - “ibm,associativity-reference-points” - - - - - - - - “ibm,max-associativity-domains” - - - - - - - “ibm,configure-kernel-dump” - - - - - - - - “ibm,configure-kernel-dump-sizes” - - - - - - - - “ibm,configure-kernel-dump-version” - - - - - - - - “ibm,read-slot-reset-state-functions” - - - - - - - “ibm,configure-pe” - - - - - - - “ibm,change-msix-capable” - - - - - - - “ibm,current-associativity-domains” - - - - - - - vdevice - - - - - “ibm,drc-names” - - - - - - - “ibm,drc-info” - - - - - - children of the - vdevice node - - - - “ibm,loc-code” - - - - - - 1 Partition Migration / Hibernation -   - - - - cpu - - - - - “name” - - - - - - - “d-cache-sets” - - - - - - - “d-cache-size” - - - - - - - “i-cache-sets” - - - - - - - “i-cache-size” - - - - - - - “bus-frequency” - - - - - - - “ibm,extended-bus-frequency” - - - - - - - - “ibm,extended-clock-frequency” - - - - - - - “clock-frequency” - - - - - - - “timebase-frequency” - - - - - - - “l2-cache” - - - - - - - “performance-monitor” - - - - - - - “ibm,associativity” - - - - - - TLB properties (See - ) - - - - - - “slb-size” - - - - - - - “ibm,tbu40-offset” - - - - - - - “ibm,pi-features” - - - - - - - “ibm,spurr” - - - - - - - “ibm,pa-optimizations” - - - - - - - “ibm,dfp” (sign bit - only) - - - - - - “ibm,sub-processors” - - - - - - - cache - - - - - “d-cache-sets” - - - - - - - “d-cache-size” - - - - - - - “i-cache-sets” - - - - - - - “i-cache-size” - - - - - - - l2-cache - - - - - - - options - - - - - “ibm,dasd-spin-interval” - - - - - - - memory - - - - - “ibm,associativity” - - - - - - - ibm,dynamic-reconfiguration-memory - - - - “ibm,associativity-lookup-arrays” - - - - - “ibm,dynamic-memory” - “ibm,dynamic-memory-v2” - only the associativity list index fields - - - - - “ibm,memory-preservation-time” - - - - - - /chosen - - - - - “ibm,architecture-vec-5” - - byte 3 (I/O Super Page Option support parameters) - - - - - 1 Partition Migration / Hibernation -   - - - - ibm,random-v# - - - - <all> - - - - - - ibm,compression-v# - - - - <all> - - - - - - ibm,encryption-v# - - - - <all> - - - - - - ibm,memory-utilization_instrumentation-v# - - - - <all> - - - - - 2 Activate Firmware - - - - rtas - - - - - - Any - /rtas node property as defined per LoPAR - remains invariant. - - - - Any - /rtas node property or definition - extension, except for the value of a function token property*, - may change (provided that the client program has indicated - support for such property or definition extension) including - the following: - - “ibm,read-slot-reset-state-functions” - “ibm,configure-pe” - - - - *NOTE: This exception mandates that if an RTAS function - token property survives a firmware activation, the token value - of that RTAS function call does not change. - - - - - 3 Device Reconfiguration - - - - ibm,coherent-platform-facility - - - - - “compatible” - - - - - - - “status” - - - - - - - “ibm,caia-version” - - - - - - - “ibm,psl-revision” - - - - - - - “ibm,vpd-size” - - - - - - - “vendor-id” - - - - - - - “device-id” - - - - - - - “subsystem-id” - - - - - - - “subsystem-vendor-id” - - - - - - - “revision-id” - - - - - - - “class-code” - - - - - - - ibm,coherent-platform-function - - - - - “compatible” - - - - - - - “reg” - - - - - - - “ibm,max-ints-per-process” - - - - - - - “ibm,min-ints-per-process” - - - - - - - “ibm,#processes” - - - - - - - “ibm,config-record-type” - - - - - - - “ibm,config-record-size” - - - - - - - “ibm,#config-records” - - - - - - - “ibm,error-buffer-size” - - - - - - - “ibm,vpd-size” - - - - - - - “ibm,scratchpad-size” - - - - - - - “vendor-id” - - - - - - - “device-id” - - - - - - - “subsystem-id” - - - - - - - “subsystem-vendor-id” - - - - - - - “revision-id” - - - - - - - “class-code” - - - - - - - “ibm,process-mmio” - - - - - - - “ibm,supports-aur” - - - - - - - “ibm,supports-csrp” - - - - - - - “ibm,supports-prr” - - - - - - - “ibm,process-mmio-size” - - - - - - - “ibm,programming-model” - - - - - - - “ibm,programming-models” - - - - - -
- - - - - -
- -
- <emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call - - This RTAS call is used to register and unregister with the platform - a data structure describing kernel dump information. This dump - information is preserved as needed by the platform in support of a - platform assisted kernel dump option. - - - - R1--1. - - For the Configure Platform Assisted Kernel Dump - option: The platform must implement the - ibm,configure-kernel-dump RTAS call using the - argument call buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,configure-kernel-dump</emphasis> - - - - - - - - Parameter Type - - - Name - - - Values - - - - - In - - - - Token - - - - Token for - ibm,configure-kernel-dump - - - - - - Number Inputs - - - - 3 - - - - - - Number Outputs - - - - 1 - - - - - - Command - - - - 1: Register for future kernel dump - 2: Unregister for future kernel dump - 3: Complete/Invalidate current kernel dump - - - - - - Work_buffer_address - - - - When command is 1: Register for future kernel dump, - points to a structure as defined in - . - - - - - - Work_buffer_length - - - - Length of Kernel Dump Memory Structure when defined - above - - - - - Out - - - - Status - - - - 0: Success - -1: Hardware Error - -2: Busy - -3: Parameter Error - -9: Dump Already Registered - -10: Dump Active - 990x:Extended Delay - - - - -
- - - - - R1--2. - - For the Configure Platform Assisted Kernel Dump - option: The work-buffer address and work-buffer-length for the - ibm,configure-kernel-dump RTAS call must point to an - RMR-memory buffer that contains the structures described in - , whenever the command is 1, - register for future kernel dump; otherwise the call may return -3, - “Parameter Error.” - The Dump Memory Structure specified in - is passed by the operating - system during a - ibm,configure-kernel-dump RTAS call. It is also - reported by the platform using the - ibm,kernel-dump RTAS property after a dump has been - initiated. - - - Kernel Assisted Dump Memory Structure - - - - - - - - - - - Header - - - - - - - - Offset - - - Number of Bytes - - - Value - - - - - 0x0 - - - 4 - - - Dump Format Version = 0x00000001 - - - - - 0x4 - - - 2 - - - Number of Kernel Dump Sections - - - - - 0x6 - - - 2 - - - Dump Status Flags - A bit mask with value - 0x8000 = Dump performed (Set to 0 by caller of the - ibm,configure-kernel-dump call) - 0x4000 = Dump was triggered by the previous system boot - (set by platform) - 0x2000 = Dump error occurred (set by platform) - All other bits reserved - - - - - 0x8 - - - 4 - - - Offset to first Kernel Dump Section, offset from the - beginning of the Structure - - - - - 0xc - - - 4 - - - Number of bytes in a block of the dump-disk, if data to - be written to a dump-disk, If not, should be set to 0 - (indicating the no disk dump option.) - - - - - 0x10 - - - 8 - - - Starting block# offset on dump-disk (set to 0 for the no - disk dump option) - - - - - 0x18 - - - 8 - - - Number of blocks on dump-disk usable for dump (set to 0 - for the no disk dump option) - - - - - 0x20 - - - 4 - - - Offset from start of structure to a Null-terminated - Dump-disk path string (set to 0 for the no disk dump - option) - - - - - 0x24 - - - 4 - - - Maximum time allowed (milliseconds) after - Non-Maskable-Interrupt for the OS to call - ibm,configure-kernel-dump - Function 2 (unregister) to prevent an - automatic dump-reboot (set to 0 to disable the automatic - dump-reboot function) - - - - - - Dump-disk Path String - - - - - - Offset specified above - - - Varies - - - Null-terminated Dump-disk path string specifying the - dump-disk. If no disk dump option is indicated, this section is - not included. - - - - - - First Kernel Dump Section - - - - - - Offset specified above - - - 4 - - - Dump Request Flags: - A bit-mask - Bit 0x00000001 When set, firmware to copy source data to - partition memory. This option must be selected if no disk dump - option is indicated. - All other bit values reserved - - - - - Section Start+4 - - - 2 - - - Source Data type, describes section of dump memory being - described - 0x0001 = CPU State Data - 0x0002 = Hardware Page Table for Real Mode Region - 0x0011 = Real Mode Region - 0x0012 = Dump OS identified string (identifies that the - dump is for a particular OS type and version) - 0x0100 - 0xFFFF OS defined source types - All Other values reserved - - - - - Section Start+6 - - - 2 - - - Dump Error Flags (set by platform) - Bit mask - 0x8000 = Invalid section data type - 0x4000 = Invalid source address - 0x2000 = Requested section length exceeds source - 0x1000 = Invalid partition destination address - 0x0800 = Partition memory destination too small - - - - - Section Start+8 - - - 8 - - - Source address (logical address if section came from - partition memory, or byte offset if section is platform - memory) - - - - - Section Start+16 - - - 8 - - - Requested data length, represents number of bytes to - dump - - - - - Section Start+24 - - - 8 - - - Actual data length, number of bytes dumped - - - - - Section Start+32 - - - 8 - - - Destination address, logical address used for sections - not written to disk by the platform, always required for a Real - mode region section and for all sections when the no disk dump - option is used. - - - - - - Subsequent Sections - - - - - - Previous Section Start+40 - - - Start of Next Section - - - A total of up to nine additional 40 bytes sections with - values as described in the First Section may be specified so - long as the entire structure does not exceed 512 bytes for - version 1. - - - - -
- - - - - R1--3. - - ibm,os-term RTAS call, or on a system reset without - an - ibm,nmi-interlock RTAS call, if the platform has a - dump structure registered through the - ibm,configure-kernel-dump call, the platform must - process each registered kernel dump section as required and, when - available, present the dump structure information to the operating system - through the - “ibm,kernel-dump” property, updated with - status for each dump section, until the dump has been invalidated through - the - ibm,configure-kernel-dump RTAS call. - - - - - R1--4. - - If ibm,configure-kernel-dump RTAS call is made to - register or unregister for a dump while a dump is currently active, the - platform must return a - Status of -9, “Dump Active” indicating - that a dump has been copied by the platform and a call must be made to - complete/invalidate the active dump before another call to register or - unregister a dump can be completed successfully. - - - - - R1--5. - - If ibm,configure-kernel-dump RTAS call is made to - register a dump after a dump has already been registered by a call, the - platform must return a - Status of -8, “Dump Already Registered” - unless an intervening call was made to invalidate the previously - registered dump. - - - - - R1--6. - - For the Configure Platform Assisted Kernel Dump - Option: Partition memory not specifically mentioned in the call - structure must be preserved by the platform at the same location as - existed prior to the os termination or platform reboot. - - - - - R1--7. - - For the Configure Platform Assisted Kernel Dump - Option: The platform must present the RTAS property, - “ibm,configure-kernel-dump-sizes” in the - OF device tree, which describes how much space is required to store dump - data for the firmware provided dump sections, where the firmware defined - dump sections are: - - - - 0x0001 = CPU State Data - - - - 0x0002 = Hardware Page Table for Real Mode Region - - - - - - - R1--8. - - For the Configure Platform Assisted Kernel Dump - Option: The platform must present the RTAS property, - “ibm-configure-kernel-dump-version” in - the OF device tree. - - - - - R1--9. - - For the Configure Platform Assisted Kernel Dump - Option: After a dump registration is disabled (for example, by - a partition migration operation), calls to - ibm,os-term must return to the OS as though a dump - was not registered. - - Programming Note: The intended flow of interactions - that utilize this call is as follows: - - - - The OS registers sections of memory for dump preservation during - OS initialization - - - - The OS terminates abnormally - - - - The Platform moves registered sections of memory as instructed - during dump registration. - - - - The Partition reboots and provides the prior registration data - in the device tree. - - - - The OS writes the preserved memory regions to disk before using - those memory regions for regular use - - - - The OS completes/invalidates current dump status. - - - - 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. - - - - - - -
- -
- DMA Window Manipulation Calls - - DMA windows for a PE can be changed by the OS when the platform - implements the Dynamic DMA Windows (DDW) option for a PE. The occurrence - of the - “ibm,ddw-applicable” property in any node - of the OF Device Tree indicates that the platform implements the DDW - option, but that property is required to be in the bridge above a PE in - order for the DDW RTAS call to be applicable for the PE. That is, DDW may - be applicable to some PEs in a platform and not for others. - The platform may implement the DDW RTAS calls even when the OS does - not support these, because they are not required to be used by the OS, - because there is always a default window initially allocated below 4 GB, - as specified by the - “ibm,dma-window” property. During - partition migration, these RTAS calls may come and go, but so will the - “ibm,ddw-applicable” property as the - nodes in which those are supported come or go. - The following is an example of how an OS may grab all DMA window - resources allocated for a PE: - - - - If the default window (as specified by the - “ibm,dma-window” property for the PE) is - not needed, then call - ibm,remove-pe-dma-window for the PE, specifying the - default window LIOBN, to make the maximum resources available for the - ibm,create-pe-dma-window RTAS call. - - - - Call - ibm,query-pe-dma-window for the PE to get the - Windows Available and - PE TCEs available for the PE. If the - Windows Available field indicates 1 or more and the - PE TCEs field is non-zero, then continue. - - - - Call ibm,create-pe-dma-window for the PE, specifying the - size based on the - PE TCEs field obtained from the - ibm,query-pe-dma-window RTAS call in step - and on the I/O page size being - specified. - - - - If the Windows Available field indicated 2 or more in step - , then go back to step - and repeat, otherwise - finished. - - - - Software Implementation Note: The general expectation - is that if the - “ibm,ddw-applicable” property exists for - a PE, that the OS will be able to generate one or more windows whose - total size is larger than what is available via the default window. This - requires either additional TCEs being available or that I/O page sizes - other than 4 KB are available and the PE can use the largest I/O page - size (the default window using only the 4 KB I/O page size). If not, then - removing the default window would only allow re-allocation of the same - size window at a different bus address (that is, same number of TCEs and - same I/O page size). However, it may be possible for this to happen, in - which case the platform may indicate that DDW is available to a PE, but - removal of the default window will only allow creation of the same size - window. An example is when a larger I/O page size is available but only - the TCEs in the default window are available, and the PE cannot make use - of the larger page size. - - - - R1--1. - - For the Dynamic DMA Windows (DDW) option: The - platform must implement all of the following RTAS calls: - ibm,query-dma-window, - ibm,create-dma-window, and - ibm,remove-dma-window. - - - - - R1--2. - - For the Dynamic DMA Windows (DDW) option: The - platform must provide the - “ibm,ddw-applicable” property in the OF - Device Tree in the bridge above each PE for which the DDW option is - supported. - - - - - R1--3. - - For the Dynamic DMA Windows (DDW) option: The - software must not call the - ibm,query-dma-window, - ibm,create-dma-window, or - ibm,remove-dma-window RTAS calls in the absence of - the - “ibm,ddw-applicable” property for the PE, - otherwise the call returns a - Status of -3 (Parameter error), and when the property - does exist, software must use the token values specified in the - “ibm,ddw-applicable” property for these - RTAS calls. - - - - - R1--4. - - For the Dynamic DMA Windows (DDW) option: The - platform must provide a default DMA window for each PE, and all of the - following must be true: - - - - The window is defined by the - “ibm,dma-window” property in the OF - device tree. - - - - The window is defined with 4 KB I/O pages. - - - - The window is located entirely below 4 GB. - - - - - - - R1--5. - - For the Dynamic DMA Windows (DDW) option: - The platform must remove any DMA windows created by the - ibm,create-pe-dma-window RTAS call for a PE and must - restore the default DMA window (if it was removed) for the PE, as - originally defined by the - “ibm,dma-window” properties for the PE, - in each of the following cases: - - - - On a reboot of the partition - - - - On a DR isolate operation that encompasses the PE - - - - - - - R1--6. - - For the Dynamic DMA Windows (DDW) option: - In Requirement - , the platform must provide the - same LIOBN, location, and size as specified in the - “ibm,dma-window” property in the OF - Device Tree for the device. - - - - -
- <emphasis>ibm,query-pe-dma-window</emphasis> - - This RTAS call allows for the discovery of the resources necessary - to make a successful subsequent call to - ibm,create-dma-window. - - If the ibm,query-pe-dma-window RTAS call is made with Number Outputs - equal to 6, and the “ibm,ddw-extensions” - property does not include list index of 3, - then the call will return a Status of -3 (Invalid Parameter). - - - - R1--1. - - RTAS must implement a - ibm,query-pe-dma-window call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,query-pe-dma-window</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,query-pe-dma-window - - - - - - Number Inputs - - - - 3 - - - - - - Number Outputs - - - - 5 or 6. The value 6 may be used when the ibm,ddw-extensions property - in the PHB node specified by this call indicates support for a 64-bit value of - PE TCEs. See . - - - - - - Config_addr - - - - PE configuration address (Register fields set to - 0) - - - - - - PHB_Unit_ID_Hi - - - - Represents the most-significant 32-bits of the Unit ID of - the PHB that corresponds to the - config_addr - - - - - - PHB_Unit_ID_Low - - - - Represents the least-significant 32-bits of the Unit ID - of the PHB that corresponds to the - config_addr - - - - - Out - - - - Status - - - - 0: Success - -1: Hardware Error - -3: Parameter error - - - - - Windows Available - - - Number of additional DMA windows that can be created for - this PE. If the value is 0 and the default window (as specified - by the - “ibm,dma-window” property for - the PE) has not been yet removed via the - ibm,remove-pe-dma-window RTAS call for that - window, and if the default window is not needed, then removal - of the default window makes at least one window - available. - - - - - PE TCEs hi - - - Represents the most-significant 32-bits of the largest contiguous - block of TCEs allocated specifically for (that is, are reserved for) this PE. - - - - - PE TCEs lo - - - Represents the least-significant 32-bits of the largest contiguous block - of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement - . - - - - - IO Page Sizes - - - I/O Page Size Support. I/O page sizes supported for this - PE. This is a bit significant field, defined as follows: - Bits 0 - 23 reserved - 24 = 16 GB page size supported - 25 = 256 MB page size supported - 26 = 128 MB pages supported - 27 = 64 MB page size supported - 28 = 32 MB page size supported - 29 = 16 MB page size supported - 30 = 64 KB page size supported - 31 = 4 KB page size supported - - - - - Migration Capable - - - H_MIGRATE_DMA Mask. Mask to indicate for which page sizes - (as specified in the I/O Page Size Support field), that - H_MIGRATE_DMA is supported (for this PE). This is a bit - significant field, with the bits defined to align to the bits - in the I/O Page Size Support field. - - - - -
- - - - - R1--2. - - For the Dynamic DMA Windows (DDW) option: - TCE resources returned in the - PE TCEs parameter of the - ibm,query-dma-window RTAS call must be allocated to - the PE specified by the PE configuration address specified in the call, - and must be available to a subsequent - ibm,create-dma-window RTAS call for that PE. - - - - -
- -
- <emphasis>ibm,create-pe-dma-window</emphasis> - - This call allows the creation of a new DMA window, given the size - of the DMA window, I/O page size, and the PE to which it is associated. - The return from the call includes the LIOBN of the new DMA window, the - starting I/O address of the DMA window, and size. - - Software Implementation Note: Software is expected to - not attempt to create a DMA window that is larger than possible, or - create more DMA windows than is possible, otherwise the - ibm,create-pe-dma-window will return a - Status of -3 (Parameter Error). Thus, the OS is - expected to use the - ibm,query-pe-dma-window first and not ask to create a - window that consumes more resources than those that are available to the - PE. - - - - R1--1. - - For the Dynamic DMA Windows (DDW) option: RTAS must - implement the - ibm,create-dma-window call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,create-pe-dma-window</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,create-pe-dma-window - - - - - - Number Inputs - - - - 5 - - - - - - Number Outputs - - - - 4 - - - - - - Config_addr - - - - PE configuration address (Register fields set to - 0) - - - - - - PHB_Unit_ID_Hi - - - - Represents the most-significant 32-bits of the Unit ID of - the PHB that corresponds to the - config_addr - - - - - - PHB_Unit_ID_Low - - - - Represents the least-significant 32-bits of the Unit ID - of the PHB that corresponds to the - config_addr - - - - - I/O Page Size - - - The value n, where 2 - n is the requested I/O page size. Only page - sizes obtained from the - ibm,query-pe-dma-window RTAS call for the - PE are allowed. Values of n from 0-11 are invalid. - - - - - Requested Window Size - - - The value n, where 2 - n is the requested DMA window size. - - - - - Out - - - - Status - - - - 990x: Extended delay, where x is a number 0-5 (see - text) - 0: Success (window created) - -1: Hardware Error - -2: Busy, try again later - -3: Parameter Error - - - - - - LIOBN - - - - LIOBN of the DMA window created by this call, if any. If - no DMA window was created (that is, if the - Status is not 0), then this field is - present but not used. - - - - - I/O Starting Address Hi - - - Represents the most-significant 32-bits of the starting - address on the I/O bus for the DMA window created by this call, - if any. If no DMA window was created (that is, if the - Status is not 0), then this field is - present but not used. - - - - - I/O Starting Address Low - - - Represents the least-significant 32-bits of the starting - address on the I/O bus for the DMA window created by this call, - if any. If no DMA window was created (that is, if the - Status is not 0), then this field is - present but not used. - - - - -
- - - - - R1--2. - - For the Dynamic DMA Windows (DDW) option: The - ibm,create-pe-dma-window RTAS call must return a - Status of 0 (Success) only if a window with the - requested attributes is created, and must not create a new window if a - non-0 - Status is returned. - - - - -
- -
- <emphasis>ibm,remove-pe-dma-window</emphasis> - - This RTAS call allows for the removal of PE DMA windows, including - those created with the - ibm,create-pe-dma-window RTAS call as well as the - default window specified by the - “ibm,dma-window” property for the PE. All - created DMA windows will be removed by the platform, and the default DMA - window restored, on a partition reboot, on a DR isolate operation (see - Requirement - and - ), or if the last remaining DMA - window for the PE is removed and that window is not the default DMA - window (see Requirements - and - ). After removal of a DMA - window, software needs to use the - ibm,query-pe-dma-window RTAS call to find out what - resources are available to the PE for subsequent - ibm,create-pe-dma-window RTAS call. - - - - R1--1. - - For the Dynamic DMA Windows (DDW) option: RTAS must - implement the - ibm,remove-dma-window call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,remove-pe-dma-window</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - ibm,remove-pe-dma-window - - - - - - Number Inputs - - - - 1 - - - - - - Number Outputs - - - - 1 - - - - - - LIOBN - - - - LIOBN of the DMA window to be removed. - - - - - Out - - - - Status - - - - 0: Success - -1: Hardware Error - -3: Parameter error - - - - -
- - - - - R1--2. - - For the Dynamic DMA Windows (DDW) option: The caller - of the - ibm,remove-pe-dma-window RTAS call must assure that - the TCE table specified by the - LIOBN field does not contain any valid mappings at - the time of the call (that is, that the window is not being used). - - - - - R1--3. - - For the Dynamic DMA Windows (DDW) option: - The platform must - restore the default DMA window for the PE on a call to the - ibm,remove-pe-dma-window RTAS call when all of the - following are true: - - - - The call removes the last DMA window remaining for the - PE. - - - - The DMA window being removed is not the default window. - - - - - - - R1--4. - - For the Dynamic DMA Windows (DDW) option: - In Requirement - , the platform must provide the - same LIOBN, location, and size as specified in the - “ibm,dma-window” property in the OF - Device Tree for the PE. - - - - -
- -
- Extensions to Dynamic DMA Windows - - Platforms supporting the DDW option implement extensions described - in this section. These extensions include: adding the - “ibm,ddw-extensions” property see - to those nodes that include the - “ibm,ddw-applicable” property, and - implementing the functional extensions specified for the architectural - level in - . The - “ibm,ddw-extensions” property value is a - list of integers the first integer indicates the number of extensions - implemented and subsequent integers, one per extension, provide a value - associated with that extension. Thus the property value is designed to - grow over time in such a way as to enable earlier client programs to - ignore later firmware extensions and later client programs to operate on - back level firmware. For this level of compatibility to work, the client - code needs to ignore extensions beyond what were defined when the client - code was written, and be prepared to operate on back level platforms t at - do not implement all the extensions that were defined when the client - code was written. - - - DDW Option Extensions - - - - - - - - - DDW Option LoPAR or PAPR Level - - - - - - “ibm,ddw-extensions” list - index - - - - - Value Definition - - - - - - - - 2.7 - - - 2 - - - Token of the i - bm,reset-pe-dma-windows RTAS Call - - - - - 2.7 - - - 3 - - - Value of 1 indicates the OS may invoke RTAS ibm,query-pe-dma-window - with Number Outputs equal to 6. Other values are reserved. - - - - -
- - - - R1--1. - - For compatibility with changing extensions to the Dynamic DMA - Windows (DDW) option: The client program must ignore extensions - as represented by - “ibm,ddw-extensions” value list integers - beyond those defined when the client code was written. - - - - - R1--2. - - For compatibility with changing extensions to the Dynamic DMA - Windows (DDW) option: The client program must be prepared to - operate on back level platforms that do not implement all the extensions - that were defined when the client code was written, including no - extensions at all. - - - - - -
- <emphasis>ibm,reset-pe-dma-windows</emphasis> - The - ibm,reset-dma-windows call resets the TCE table - allocation for the PE to its boot time value as communicated in the - “ibm,dma-window” OF Device Tree property - in the for the PE. - - - - R1--1. - - For the Dynamic DMA Windows (DDW) option starting with - IBM Power Architecture Platform Requirements (PAPR) - level 2.7: RTAS must implement the - ibm,reset-dma-windows call using the argument call - buffer defined by - . - - - Argument Call Buffer - <emphasis>ibm,reset-pe-dma-windows</emphasis> - - - - - - - - - Parameter Type - - - - - Name - - - - - Values - - - - - - - - In - - - - Token - - - - Token for - - - - - - - Number Inputs - - - - 3 - - - - - - Number Outputs - - - - 1 - - - - - - config_addr - - - - PE configuration address - - - - - PHB_Unit_ID_HI - - - Represents the most-significant 32-bits of the Unit ID of - the PHB that corresponds to the config_addr - - - - - PHB_Unit_ID_Low - - - Represents the least-significant 32-bits of the Unit ID - of the PHB that corresponds to the config_addr - - - - - Out - - - - Status - - - - 0: Success - -1: Hardware Error - -2: Busy, Try again later - -3: Parameter error - - - - -
- - - - - R1--2. - - For the Dynamic DMA Windows (DDW) option starting with - IBM Power Architecture Platform Requirements (PAPR) - level 2.7: The caller of the - ibm,reset-pe-dma-windows RTAS call must assure that - the TCE table(s) assigned to the PE specified by the - config_addr field contain no valid mappings at the - time of the call (that is, that the window(s) is not being used). - - - - - R1--3. - - For the Dynamic DMA Windows (DDW) option starting with - IBM Power Architecture Platform Requirements (PAPR) - level 2.7: On a call to - ibm,restore-pe-dma-windows, the platform must - restore the default DMA window per the values provided in the - “ibm,dma-window” Tree property - in the for the PE (same LIOBN, location, and size). - - - - - -
- -
- -
- -
diff --git a/pom.xml b/pom.xml index 300f7b1..d389897 100644 --- a/pom.xml +++ b/pom.xml @@ -17,11 +17,11 @@ - - Error Handling + LoPAR +