System Binding

OF Platform Extensions This section defines OF properties, methods, device tree structure and Client Interface Service requirements for LoPAR platforms. The naming conventions for IBM unique OF properties and devices are as follows: Properties created for use only by IBM compatible implementations must have the string “ibm,” as a prefix to the property name. Property names prefixed with the string “ibm,fw-” are reserved for and must be controlled by the Firmware Area. An IBM property name which does not have the firmware or AIX prefix must be defined in this document unless documented elsewhere. The value of a device “name” whether reported through the compatible property or name property for a device implemented by IBM must contain the string “IBM,” as a prefix unless it conforms to a binding which specifies otherwise.

Properties for Dynamic Reconfiguration The following property, when present, replaces the following four properties: “ibm,drc-indexes”, “ibm,drc-names”, “ibm,drc-types” and “ibm,drc-power-domains”. This property is defined for all dynamically reconfigurable platform nodes. “ibm,drc-info” property name that defines all required DR information in a new format prop-encoded-array: The first element of the array is the number of drc-info entries, encoded with encode-int The drc-info entry consists of the following elements: The drc-type encoded with encode-string. Examples include “MEM” “PHB” and “CPU” The drc-name-prefix encoded with encode-string. Examples include “LMB” “PHB “ “CPU “ and “U8233.E8B.1000C9P-V1-C” The drc-index-start encoded with encode-int. The first drc-index of the first entity in the sequence of entities described by this ibm,drc-info entry. The drc-name-suffix-start encoded with encode-int. The integer value that is to be converted to asci and appended to the drc-name-prefix to create the complete drc-name of the first entity in the sequence of entities described by this ibm,drc-info entry. The number-sequential-elements encoded with encode-int. The number of sequential entities described by this ibm,drc-info entry. The sequential-increment encoded with encode-int. The number by which to increment the drc-index and the name-suffix for each sequential entity. The drc-power-domain encoded with encode-int. The following properties have been replaced by the “ibm,drc-info” but are documented here for legacy purposes: “ibm,drc-indexes” property name denotes an integer index to be used to communicate to the firmware what connector is to be operated upon for the various RTAS calls used for DR. prop-encoded-array: An integer encoded as with encode-int, followed by a list of integers also encoded as with encode-int. For each DR connector, a unique integer index is provided which uniquely identifies the DR connector for purposes of the ibm,configure-connector, set-indicator, and get-sensor RTAS calls. The first element of the array is the number of connectors associated with the node. The second element of the array is the index which represents the first connector associated with the node, the third element the second connector, and so on until all of the node’s DR connectors are specified. “ibm,my-drc-index” property name denotes an integer index (value of the entry in the “ibm,drc-indexes” property) for the connector between the node and the node’s parent. prop-encoded-array: An array of integers encoded as with encode-int. “ibm,drc-names” property name describes the external labeling of the DR connectors. prop-encoded-array: An integer encoded as with encode-int, followed by a list of strings each encoded as with encode-string. For each DR connector, a unique human-readable name for a connector. The first element of the array is the number of connectors associated with the node. The second element of the array is the human-readable name which represents the first connector associated with the node, the third element the second connector, and so on until all of the node’s DR connectors are specified. “ibm,drc-power-domains” property name gives the power domain number for each connector associated with the node, which is the domain number to be used in the set-power-level RTAS call, if necessary. prop-encoded-array: An integer encoded as with encode-int, followed by a list of integers also encoded as with encode-int. For each DR connector, the power domain which will be controlled for DR operations (the power domain in which the DRC resides), and which will be used, if not -1, in the set-power-level RTAS call for the connector. The power domain number of -1 denotes a live-insertion power domain (in which case, the set-power-level RTAS call is not used). The first element of the array is the number of connectors associated with this node. The second element represents the domain number for the first connector. The element following this is the domain number for the second connector, and so on until all of the node’s DR connectors are specified. “ibm,drc-types” property name, describes the type of each connector associated with the node, in a human-readable form. prop-encoded-array: An integer encoded as with encode-int, followed by a list of strings each encoded as with encode-string. The first element of the array is the number of connectors associated with this node. The second element of the array is the connector type of the first connector associated with the node, the third element the second connector, and so on until all the node’s DR connectors are specified, and these elements will be one of the currently defined connector types specified in . Currently Defined DR Connector Types Connector Type(character string) Description 1 A 32-bit, 5 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz Only. 2 A 32-bit, 5 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz. 3 A 32-bit, 3.3 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz Only. 4 A 64-bit, 5 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz Only. 5 A 64-bit, 5 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz. 6 A 64-bit, 3.3 Volt conventional PCI slot which accommodates cards that operate up to 33 MHz Only. 7 A 32-bit, 3.3 Volt conventional PCI slot which accommodates cards that operate up to 66 MHz. IOAs that operate up to 66 MHz will only operate at frequencies above 33 MHz if there are no 33 MHz IOAs on the same bus. 8 A 64-bit, 3.3 Volt conventional PCI slot which accommodates cards that operate up to 66 MHz. IOAs that operate up to 66 MHz will only operate at frequencies above 33 MHz if there are no 33 MHz IOAs on the same bus. 9 Reserved 10 Reserved 11 A 32-bit PCI-X capable slot which accommodates cards that operate up to 66 MHz 12 A 32-bit PCI-X capable slot which accommodates cards that operate up to 100 MHz 13 A 32-bit PCI-X capable slot which accommodates cards that operate up to 133 MHz 14 A 64-bit PCI-X capable slot which accommodates cards that operate up to 66 MHz 15 A 64-bit PCI-X capable slot which accommodates cards that operate up to 100 MHz 16 A 64-bit PCI-X capable slot which accommodates cards that operate up to 133 MHz 17 A 64-bit PCI-X capable slot which accommodates cards that operate up to 266 MHz 18 A 64-bit PCI-X capable slot which accommodates cards that operate up to 533 MHz 19 A PCI Express Rev 1 slot with 1x lanes. 20 A PCI Express Rev 1 slot with 2x lanes. 21 A PCI Express Rev 1 slot with 4x lanes. 22 A PCI Express Rev 1 slot with 8x lanes. 23 A PCI Express Rev 1 slot with 16x lanes. 24 A PCI Express Rev 1 slot with 32x lanes. 25 A PCI Express Rev 2 slot with 1x lanes. 26 A PCI Express Rev 2 slot with 2x lanes. 27 A PCI Express Rev 2 slot with 4x lanes. 28 A PCI Express Rev 2 slot with 8x lanes. 29 A PCI Express Rev 2 slot with 16x lanes. 30 A PCI Express Rev 2 slot with 32x lanes. CPU Logical CPU MEM Logical Memory Region MEM-n (where n is a non-zero integer) Extended Logical Memory Region(s). Used with the Reserved Memory option. PHB Logical PCI Host Bridge SLOT Logical I/O slot PORT Logical Port

“ibm,phandle” property name, defines the phandle for the node. prop-encode-array: An integer encoded with encode-int.

OF Root Node This section defines additional properties and methods associated with LoPAR platforms that OSs expect to find in the root node. Unit addresses in an LoPAR system are limited to 60 bits in length corresponding to the maximum real address supported by the POWER processor architecture. The unit address of all non-system nodes that are children of the root node shall have the same value each time the platform is booted; i.e., shall be invariant for each boot process. Notes: This requirement ensures that the PHB would have a stable unit address. Violations of this rule may require reinstallation of an OS. The recommended practice is to generate a virtual unit address for PHB nodes. This is done by giving a zero length to its first reg property with an address that is selected such that it remains constant. In single bridge platforms, the value is chosen based upon historical precedent of the predecessor product. In multi-enclosure platforms, the virtual unit address is based upon the manufacturing serial number to insure uniqueness.

Root Node Properties This section defines the additional properties or values which shall be present in the root node unless otherwise specified. “#address-cells” [S] Standard property name, encoded as with encode-int, that specifies the number of cells required to represent physical addresses on the processor bus. The value of “#address-cells” for the processor bus shall be 1 or 2 depending on whether there is any memory addressable at or above 4GB’s. “#size-cells” [S] Standard property name, encoded as with encode-int, that specifies the size of cells required to represent physical addresses on the processor bus. The value of “#size-cells” for the processor bus shall be 1 or 2 depending on whether there is any memory addressable at or above 4GB’s. “clock-frequency” [S] Standard property name, encoded as with encode-int, that represents the primary system bus speed (in hertz). “ibm,extended-clock-frequency” property name: Property that represents the primary system bus speed in hertz of this node. This property allows the encoding of multi-giga-hertz quantities. prop-encoded-array: Consisting of two cells (freq-hi, freq-lo) each encoded as with encode-int, such that their combined value is (freq-hi || freq-lo). “system-id” [S] Standard property name, encoded as with encode-string, that contains the identification of the computer system (Reference the “name” property in ). This string should be unique across all systems and all manufacturers. An example of an address of this form is “0nnnnnnmmmmmm” where nnnnnn is a sequence of 6 uppercase hexadecimal digits representing a 24-bit value that identifies manufacturer and mmmmmm is a sequence of 6 uppercase hexadecimal digits representing a 24-bit binary number assigned by the manufacturer to assure uniqueness. Note: For platforms with built-in ethernet or other IEEE 802-style interfaces, the 6-byte MAC address assigned to that interface meets the requirements and could be used as the system-id. “model” [S] Standard property name that is a printable string identifying the manufacturer and model number of the platform. prop-encoded-array: Text string, encoded as with encode-string. The value of this property is a vendor dependent string which identifies this platform via its manufacturer and model number. “device_type” [S] Standard property name that is a printable string identifying the platform as LoPAR Compliant. prop-encoded-array: Text string, encoded as with encode-string. The value of this property is a string, “chrp” which identifies the platform is LoPAR Compliant. “ibm,lpar-capable” property name indicates that the platform is capable of supporting logical partitioning and is only present on such systems. This property is, however, present even if the platform is not currently configured for logical partition operation. prop-encoded-array: <NULL> “ibm,converged-loc-codes” property name indicates that the platform supports the “Converged Location Code” option. This property shall be present only on platforms that support the “Converged Location Code” option. prop-encoded-array: <NULL> “ibm,max-boot-devices” property name indicates the maximum number of boot-device entries that the OF automatic boot code will process (entries after this number are ignored). Platforms that do not present this property default to process a maximum of 5 entries. prop-encoded-array: an integer encoded as with encode-int. “ibm,aix-diagnostics” property name indicates that the platform is capable running AIX diagnostics. prop-encoded-array: <NULL> “ibm,diagnostic-lic” property name, presented to partitions authorized to perform diagnostic operations, that indicates that the platform is designed to use the specified license internal code package for diagnostic services. prop-encoded-array: one or more encapsulated package handles encoded as with encode-int. “ibm,io-server-lic” property name indicates that the platform is designed to use the specified license internal code package for I/O services. prop-encoded-array: one or more encapsulated package handles encoded as with encode-int. “ibm,plat-res-int-priorities” property name that designates to the client program that the platform has reserved one or more interrupt priorities for its own use. prop-encoded-value: one or more ( interrupt priority, range) pairs, where interrupt priority is a single cell hexidecimal number between 0x00 and 0xFF, and range is an integer encoded as with encode-int that represents the number of contiguous interrupt priorities that have been reserved by the platform for its internal use. “ibm,eeh-default” property name indicates the platform’s default setting for the EEH option. prop-encoded-array: An integer encoded as with encode-int that represents the platform’s default setting for the EEH option. The defined states are: 0= The platform boots up with the EEH option disabled. 1= The platform boots up with the EEH option enabled. “ibm,model-class” property name to indicate the platform class. prop-encoded-array: string encoded as defined in . Example Encoding Strings Encoded String Platform Class C5 Blade/Entry D5 Entry E5 Entry F5 Mid-range G5 High-end H5 High-end P5 obsolete

“ibm,partition-no” [S] property name to define the partition number of this particular logical partition as established by the Hardware Management Console. prop-encoded-array: The logical partition number is a one cell integer encoded as with encode-int. “ibm,partition-name” [S] property name to define the partition name of this particular logical partition as established by the Hardware Management Console. prop-encoded-array: A NULL terminated string. “ibm,platform-hardware-notification” property name indicating to the OS the presence of hardware for which the OS may need to take action. This property exists to notify the OS of hardware elements on the platform which may require special handling by the OS, such as in response to a hardware errata. prop-encoded-array: An integer encoded as with encode-int followed by a list of strings encoded as with encode-string. The first element represents the number of strings to follow in the property. Each string in the array names a hardware element that may require the OS to take specific action. The intention is that the string is to name the hardware element being reported. It is not the intention to define (or even hint at) the action that the OS must take. It is expected that some source outside this document will contain a cross reference between these strings and documentation such as hardware errata notes which define the action the OS must take. If the “ibm,platform-hardware-notification” property is provided and a string begins with the <name> field of the “name” (see ) property in the CPU nodes followed by an underscore, the characters following the underscore are a hexadecimal representation of the contents of a Processor Version Register that the platform may contain. “ibm,fault-behavior” property name to define the behavior of the Error Log indicator relative to FRU faults. prop-encoded-array: An integer encoded as with encode-int that represents how the Error Log indicator should be handled when a FRU fault is detected. Property non-existent -- The OS may set FRU Fault and Error Log indicators for all errors (those it detected and those that the platform reports to the OS). Property exists with a value of 1 -- The OS only sets FRU Fault and Error Log indicators for errors it detects. “ibm,fru-9006-deactivate” property name to define whether or not the OS should deactivate 9006 indicators that it has activated. prop-encoded-array: An integer encoded as with encode-int that represents how the OS should behave relative to FRU Fault indicator deactivation. Property non-existent -- The OS is responsible for deactivating FRU level 9006 indicators that it has activated. Property exists with a value of 1 -- The OS should not deactivate FRU level 9006 indicators that it has activated, but is allowed to do so (firmware does not block). The deactivation of the FRU level 9006 indicators is platform and service procedure dependent. “compatible” [S] Standard property name that conveys the platform architecture identifiers. prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, each encoded with encode-string. Specifies a list of platform architectures with which this platform is compatible. This is used by a client program when it is trying to determine the appropriate support for this platform. This property shall include the substring “LoPAR-<LoPAR version>-<Manufacturer>-<Manufacturer Version>” where <LoPAR version> is the text (without blanks) after the word “Version” on the cover page of the LoPAR specification that the platform adheres to, <Manufacturer> is a unique string identifying the manufacturer of the platform (see the OF standard description of the “name” property for suggestions), and <Manufacturer_Version> is defined by the manufacturer of the platform. Note: In order to comply with the OF Standard description of the “compatible” property, implementations should place the “LoPAR-<LoPPR version>-<Manufacturer>-<Manufacturer Version>” substring after values that were present in the “compatible” property prior to the inclusion of the “LoPAR-<LoPAR version>-<Manufacturer>-<Manufacturer Version>” substring. “ibm,max-vios-function-level” property name to define the maximum vios function level that a client shall permit. prop-encoded-array: An integer encoded as with encode-int that represents the maximum VIOS level that the client shall negotiate. See for the definition of the values of this property. “ibm,partition-performance-parameters-level” property name to define the level of partition performance parameter reporting supported by the platform. prop-encoded-array: An integer encoded as with encode-int that represents the level of partition performance parameter reporting supported by the platform (See ). Level of Partition Performance Parameter Reporting Supported Partition Performance Parameter Level Description 0 Base Level 1 Addition of Processor Virtualization Resource Allocations to H_GET_PPP and Virtualization Processor idle count to H_PIC

“ibm,preconfigure-usb-kvm” property name the presence of which indicates that the platform requires the operating system to force configuration of the USB keyboard/mouse nodes during its configuration phase. prop-encoded-array: <NULL> This property, when present in the root node, indicates that the platform requires the operating system to force pre-configuration of USB keyboard/mouse nodes internally during its configuration phase. This property is presented only by platforms with a KVM switch that desire to force configuration by one or more target operating systems that do not fully support dynamic addition of USB keyboard and mouse unless the USB keyboard and mouse are actually seen during the operating system configuration phase, but may be present even if the KVM switch is not present when the device tree is inspected. Forced pre-configuration is needed since the operating system may not actually see the USB keyboard and mouse during its configuration phase due to the KVM switch that the platform uses only shows USB keyboard and mouse when those devices are actually switched to the appropriate KVM switch port. “ibm,enable-ci64-capable” property name to define the platform supports the “ibm,enable-ci64” method in the Client Interface. prop-encoded-array: None, this is a name only property. “ibm,migratable-partition” property name indicating that the platform supports the potential migration of this partition. prop-encoded-array: <NULL> “ibm,extended-address” [S] property name indicates this platform supports Peripheral Memory Spaces, Peripheral I/O Spaces, and SCA spaces above 4 GB. prop-encoded-array: <none> This property must be present. “ibm,ignore-hp-po-fails-for-dlpar” property name to define that the OS may ignore failures of Hot Plug power off and isolate operations during a DLPAR remove operation. See also Note 2 in . prop-encoded-array: None, this is a name only property. “ibm,managed-address-types” property name that conveys the platform's supported types of external addresses that are reprogrammable. prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings as described in , each encoded with encode-string. Address types supported in <emphasis role="bold"><literal>“ibm,managed-address-types”</literal></emphasis> property Text String Description ethernet_mac Ethernet MAC address ethernet_vlan Ethernet VLAN ID (for default traffic) san_wwn Fibre Channel World Wide Name (covers both Port & Node names) sas_wwid SAS IOA's WWID value

“ibm,service-indicator-mode” property name indicates in which service indicator mode the platform is operating. prop-encoded-array: an integer encoded as with encode-int that represents the mode. Defined values are: 0 = Platform is operating in the Guiding Light mode. 1 = Platform is operating in the Lightpath mode. “ibm,guid-partition-table” property name indicates that the partition supports disks with the GUID Partition Table. prop-encoded-array: <NULL> “ibm,linux-le-capable” property name indicates that the partition is capable of supporting boot of Little Endian Linux. prop-encoded-array: <NULL> “ibm,partition-uuid” property name specifies a universally unique identifier for this partition. prop-encoded-array: A string of data as described below, encoded as with encode-string The Universally Unique IDentifier (UUID) option provides each partition with a Universally Unique Identifier that is persisted by the platform across partition reboots, reconfigurations, OS reinstalls, partition migration, hibernation etc. The UUID is a 16 byte string of format fields and random bits as defined in . The random bits are generated in an implementation-dependent manner to achieve a projected probability of collision of not greater than one in 260. UUID Format Field Byte:Bit Size (Bits) Values Version 0:0 1 0: Initial Version 1: Reserved Random Bits 0:1 thru 5:7 47 Random Bits Generation Method 6:0-3 4 0b0000 Never Used 0b0100 Random Generated All other values are reserved Random Bits 6:4 - 7:7 12 Random Bits Variant 8:0-1 2 0b10 DCE Variant UUID All other values are reserved Random Bits 8:2 - 15:7 62 Random Bits

For the GET_PARTNER_UUID subfunction (See ), the data is represented as 16 bytes as described in . For the ibm,partition-uuid property, the data is represented as a string of hexadecimal characters, with hyphens added for readability. Hexadecimal values a through f are lower case. An example of the string representation of the UUID is 648a9ca6-1fb4-4f7e-9436-14d015f3dd74 Implementation Notes: In the absence of this property, the determination of how the OS is to behave is made by the platform presenting or not presenting FRU Fault indicators to the OS see chapter . In the case where there are no FRUs owned by the partition, the OS will not observe any FRU Fault indicators assigned, even when the platform is operating in the Lightpath mode. Presenting this property does not imply any relaxation of the requirements spe3cified in chapter .

Properties of the Children of Root “ibm,9009-domain” property name that defines the index for a 9009 reset component indicator, and if it exists, the corresponding 9009 sensor, for the node in which the property exists. Multiple nodes may have the same index, indicating that they belong to the same reset domain; including nodes which are not descendents of the node which contains this property. Descendents of a node containing this property will be in the same reset domain. prop-encoded-array: An integer encoded as with encode-phys that represents the index for the indicator, and if it exists, for the corresponding sensor. “ibm,associativity” property name to define the associativity domains for this resource. prop-encoded-array: One or more associativity lists. Each associativity list consisting of a number of entries integer (N) encoded as with encode-int followed by N integers encoded as with encode-int each representing an associativity domain number.

Root Node Methods This section defines methods associated with the platform via “/” (the root node). Boot Loader Note: The suggested behavior for boot loader client programs: Check the “ibm,rpa-client-config” property to see if the platform recognized the “ignore-my-settings” bit in the boot loader image i.e. YABOOT for LINUX. If recognized, check for existence of “ibm,client-architecture-support” and invoke that method with the >ibm,??? compatible (wording???) with the Real Base and Real Size constraints of the kernel being loaded. If that method did not exist, invoke “PROCESS-ELF-HEADER” from /packages/elf-loader with a simulated ELF-header that the Linux kernel is compatible with. ibm,client-architecture-support (ibm,architecture.vec -- err?) This method is called via the call-method Client Interface Service, prior to starting other partition processors or threads, to communicate to the platform, via the ibm,architecture.vec structure, the architecture options that are supported by the client program. Based upon this knowledge the platform configures itself and the device tree to represent the most functional programming environment supported by the combination of the platform, client program and user specified constraints. If multiple partition processors or threads are active at the time of the ibm,client-architecture-support method call, or an error is detected in the format of the ibm,architecture.vec structure, the err? boolean shall be TRUE; else FALSE. The ibm,architecture.vec input parameter is the starting address of a self defining structure in contiguous memory. Some bits within the ibm,architecture.vec structure option vectors represent policies. When set, and an associated condition is detected, the ibm,client-architecture-support method does not return and processing continues as with a boot failure of the client program. The LoPAR architecture options that are selected by this method are communicated in the value of the “ibm,architecture-vec-5” property of the /chosen node. To ensure the greatest level of interoperability, the client program should constrain itself to using the set of instructions and environment specified for first level interrupt handlers, see Book III of the , while not attempting access to potentially optional SPRs or the MSR prior to invoking the ibm,client-architecture-support root node method. Architecture and Implementation Notes: Most of the IBM,RPA-Client-Config ELF header functionality is subsumed by the ibm,client-architecture-support root method. However, the ibm,client-architecture-support root method does not support the functionality specified through the ns.min-load field of the IBM,RPA-Client-Config ELF header. Supporting firmware implementations are prepared to move themselves out of the way when loading client programs. When booting a client program, firmware processes an IBM,RPA-Client-Config ELF header if present; a subsequent call of the ibm,client-architecture-support root method with conflicting values in the ibm,architecture.vec structure, overrides the configuration variables set by the ELF header. Formal definition of ibm,architecture.vec: ibm,architecture.vec = a PVR-list: Number-of-option-vectors: option-vectors[Number-of-option-vectors + 1] PVR-list = Terminator-list-entry | Non-terminator-list: Terminator-list-entry Non-terminator-list = Non-terminal-list-entry | Non-terminal-list-entry : Non-terminator-list List-entry = 4-byte-mask: 4-byte-PVR-value Terminator-list-entry = List-entry such that ! 4-byte-mask & 4-byte-PVR-value != 0x00000000 Non-terminator-list-entry = List-entry such that ! 4-byte-mask & 4-byte-PVR-value == 0x00000000 Number-of-option-vectors = The number of option vectors is n+1 where n is the numeric value of the byte (byte value of 0x00 represents one option vector) option-vector (option-vectors number 1-255): 1 byte length of the option vector where the number of bytes in the option vector (including the first byte of length) is n+2 where n is the numeric value of the byte (byte value of 0x00 represents a two byte option vector -- one length byte and one bit-vector byte) followed by 1-256 bytes of bit-vector. option-vector (option-vector number 256): is special in that it is reserved for expansion. The first byte is again the number of option vectors in the vector expansion (see definition of Number-of-option-vectors above). This is followed by 1-255 option-vectors (see definition above) and potentially a 256th option-vector which is again an expansion option vector, and so on. bit-vector: The structure of a bit vector is vector specific, in general support for most options are indicated by setting a specific bit to a 1, see . The PVR-list of the ibm,architecture.vec structure is processed for the PVR value of each processor that the client program may be exposed to until either a List-entry allows the process to continue, or the Terminator-list-entry has been processed. If no List-entry allows the process to continue, then the ibm,client-architecture-support method terminates partition operation as with a boot failure. A List-entry allows the process to continue if either of the two following conditions hold. (Processor-PVR-value & List-entry[4-byte-mask]) == (List-entry[4-byte-PVR-value] & List-entry[4-byte-mask]) /*The client program explicitly supports the processor implementation */ If (the processor requires no client support for errata) && (Logical-Processor-PVR-value & List-entry[4-byte-mask]) == (List-entry[4-byte-PVR-value] & List-entry[4-byte-mask]) /* Client program specifies support for this level of architecturally compliant processors */ List-entry values of special interest (these are Terminator-list-entry values): 0x00000000 0xFFFFFFFF Single entry list that matches any PVR value 0xFF000000 0x0FFFFFFF Single entry list that matches all architecturally compliant processors. ibm,architecture.vec option vectors Option Array Option Vector Byte Number Bit Number Description Base 1 PowerPC Server Processor Architecture Level 6 1 0 Ignore 1 Cessation Policy 2 Reserved for Expansion (0b0) 3 4 5 6 7 2 0 2.00 1 2.01 2 2.02 3 2.03 4 2.04 5 2.05 6 2.06 7 2.07 3 0 2.08 1-7 Reserved for Expansion (0b0) 4-256 Reserved for Expansion Base 2 Open Firmware 1 0 Ignore 1 Reserved 2 real-mode 3 Reserved for Expansion (0b0) 4 5 6 7 2-3 0-15 Reserved for Expansion (0x0000) 4-7 real-base 0-31 OF real starting address or -1 for platform default 8-11 real-size 0-31 Maximum OF size or -1 for platform default 12-15 virt-base 0-31 OF starting virtual address or -1 for platform default (valid for real-mode = 0) 16-19 virt-size 0-31 Maximum OF virtual size or -1 for platform default (valid for real-mode = 0) 20-23 load-base 0-31 Starting address of the client program load or -1 for platform default 24-27 min-rma-size 0-31 Minimum size of RMA in MB (total bytes = N*(2**20)) 28-31 min-load 0-31 Minimum client code to load at load-base or -1 for full client program at load base 32 min-rma% 0-8 RMA size => M% * Partition_memory_size where M is the value of this 8 bit field 33 max-pft-size 0-8 The maximum size of the hash page table as 2**n 17<n<46 34-256 Reserved for Expansion Base 3 IBM PowerPC Server Processor Options 1 0 Ignore 1 Cessation Policy 2 Reserved for Expansion (0b0) 3 4 5 6 7 2 0 Floating Point 1 VMX 2 Decimal Floating Point 3 Decimal Floating Point Facility (The value of the ibm,dfp property indicates the architecture level of the facility.) 4 Reserved for Expansion (0b0) 5 6 7 3-256 Reserved for Expansion Base 4 LoPAR Implementation 1 0 1 Cessation Policy 2 ibm,change-msi busy: If set, the client program supports RTAS ibm,change-msi returning a -2 (Call again) or 990x (Extended delay) 3 Reserved for Expansion (0b0) 4 5 6 7 2 0-7 Minimum VP entitled capacity percentage * 100 (if absent assume 10%) 2-256 Reserved for Expansion Base 5 LoPAR or OF Options 1 0 Ignore 1 Cessation Policy 2 64 bit PE TCEs : If set, the client program supports ibm,query-pe-dma-window returning a 64-bit value for PE TCEs 3 Reserved for Expansion (0b0) 4 5 6 7 2 0 Logical Partitioning: If set the client program supports logical partitioning and associated hcall()s; else the client program shall be run with the hypervisor bit on. 1 Shared Processor Logical Partitioning: If set the client program supports the Shared Processor LPAR Option and may be run with that option enabled; else the Shared Processor LPAR Option shall be disabled for this partition. 2 ibm,dynamic-reconfiguration-memory: If set the client program supports the “ibm,dynamic-reconfiguration-memory” property and it may be presented in the device tree; else, the partition memory shall be represented with individual memory nodes. 3 Large Pages: If this bit is set, the client supports pages larger than 4 KB; else, the platform shall represent all of memory as mapped via 4 K pages. 4 Alpha Partition 5 Tolerate long delays in H_MIGRATE_DMA 6 Client supports donating dedicated processor cycles 7 PCI Express/MSI Support: If set, the client supports PCI Express implementations utilizing Message Signaled Interrupts (MSIs). 3 0 On input to ibm,client-architecture-support a non-zero value indicates that the client supports the I/O Super Page Option (Support of >4K I/O pages) (Includes extensions to H_MIGRATE_DMA for >4K I/O pages and >256 xlates). See . In the ibm,architecture-vec-5 property of the /chosen node, a non-zero value indicates that the platform supports the I/O Super Page Option (Support of >4K I/O pages). 1-4 On input to ibm,client-architecture-support this field shall be zero. In the ibm,architecture-vec-5 property of the /chosen node, this field represents the implementation dependent number of xlates entries supported per migration operation as: 256 * 2**N. See . 5-7 On input to ibm,client-architecture-support this field shall be zero. In the ibm,architecture-vec-5 property of the /chosen node, this field represents the implementation dependent number of simultaneous migration options supported as: 2**N. See . Base 5 LoPAR or OF Options 4 Cooperative Memory Over-commitment Option Control 0 The value of 1 enables the Cooperative Memory Over-commitment Option 1 The value of 1 enables the Extended Cooperative Memory Over-commit Option 2-7 Reserved for Expansion 5 Associativity Information Option Control 0 = the “Form value” of the “ibm,associativity” and “ibm,associativity-reference-points” properties. See for further details. 1 Platform Resource Reassignment Notification (Affinity Change) 2-7 Reserved for Expansion 6 Binary Option Controls 0 Enable MTT Option See . 1 Reserved 2 Enable Active Memory Compression 3 Reserved for Expansion 4 Reserved for Expansion 5 Enable Hotplug Interrupts See Hot Plug Events in . 6 Enable Support for Multiple Hotplug Slots per PHB 7 Reserved for Expansion 7 Reserved for Expansion 8 SRIOV Virtual Functions Options 0 SRIOV Virtual Functions Support Dynamic DMA Windows (DDW): 0: SRIOV Virtual Functions do not support DDW 1: SRIOV Virtual Functions do support DDW 1-7 Reserved For Expansion 9-12 Max Processors Supported (For legacy support, if this byte is not present the partition is limited to a maximum of 64 processors) 0-31 32 bit unsigned integer maximum number of OF device tree nodes of type “cpu” that may be presented to this partition. 13-14 0-7 & 0-7 Highest Base LoPAR Level Supported as the binary contents of 13.14 (i.e. level 4.15 would be encoded as 0x040F) 15-16 Memory Reference Instrumentation 0 Reference History Array 1 Access Rate Array 2 Affinity Domain Access Log 3-15 Reserved for Expansion Base 5 LoPAR or OF Options 17-20 Platform Facilities Enable – Value of 0b1 indicates facility is enabled 0 Random Number Generator 1 Compression Engine 2 Encryption Engine 3-31 Reserved for Expansion -- Value = 0b0 21 0-7 Sub-Processor Representation Level -- Defined Values: 0: Sub-Processors not supported 1: 1,2,or 4 Sub-Processors supported 2-255 Reserved 22 0 If set the client program supports the “ibm,dynamic-memory-v2” property in the “ibm,dynamic-reconfiguration-memory” node and it may be presented in the device tree; else, the “ibm,dynamic-memory” property shall be represented. 1 If set the client program supports the “ibm,drc-info” property definition and it may be presented in the device tree; else, the “ibm,drc-indexes”, “ibm,drc-types”, “ibm,drc-names”, and “ibm,drc-power-domains” properies shall be presented. 2-7 Reserved for Expansion 23-256 Reserved for Expansion Base 6 Hints 1 0 Reserved for Expansion (0b0) 1 2 3 4 5 6 7 2 0 Secondary Page Table Entry Group: If set, the client does not use secondary page table entry groups; else the client may use secondary page table entry groups. 1 Reserved 2 3 4 5 6 7 3 0-7 OS Name: Represents the name of the client OS. Defined values include: 0x0: Reserved 0x1: AIX 0x2: Linux 0x3-0xFF: Reserved for Expansion 4-256 Reserved for Expansion 7 OS Identification 1-256 An ASCII character formatted null terminated string that describes the client operating system. The string shall be human readable and may be displayed on the console. 8-255 Reserved for Expansion 256 Reserved for Expansion to the first Extension Option Array Extensions 1-N Reserved for Expansion

Notes: The Ignore Policy bit indicates that the client program assumes all responsibility for the options represented by the option vector. The firmware is to configure the platform at the highest level consistent with its configuration variables and ignore the rest of the specific option vector. An option vector with the Ignore Policy bit set need be no longer than two bytes (size=0, data = 0b1ddd dddd where d = don’t care). The Cessation Policy Bit determines if the partition continues to run if the platform must operate with an option enabled that is not explicitly supported by the client program as represented by the option vector setting. If the Cessation Policy Bit is 1, then processing halts as with a boot failure. If the Cessation Policy Bit is 0 then client program processing continues if the unsupported option is initialized to a benign state and stays in that state unless an aware program activates the option, and the option does not appear in the device tree. If an unsupported option cannot be initialized to a benign state, then processing halts with a boot failure. Following are the detailed definitions of benign state for selected bit vectors. For option vector numbers 1 “PowerPC Server Processor Architecture Level” and 3 “IBM PowerPC Server Processor Extensions” the benign state is defined as unable to generate exceptions, mask errors, or present covert channel exposures. For option vector number 5 “LoPAR Options” Byte 2 bit 5 “Alpha Partition” The Cessation Policy bit is not applicable. For option vector number 2 “Open Firmware” the Cessation Policy Bit is not defined, the platform either accommodates the values defined in the option vector or proceeds as with boot failure. The Initial size of the RMA is set to the greater of the values indicated by bytes 24-27 or 32 of option vector number 2 “Open Firmware” or minimum RMA size supported by the platform and capped by the maximum memory defined for the partition and the maximum size of the RMA supported by the platform. The respective selected values are reported in the length of the first memory property. The Alpha flag only applies to the first partition of a non HMC managed system and activates overrides to the partition's I/O resource allocation as defined in the partition definition. If the system is HMC managed, the flag is ignored and the client program gets the resources assigned by its partition definition (no overrides are activated). If the partition is not the first partition, the flag is ignored and the client program gets the resources assigned by the partition definition (no overrides are activated). If the Alpha flag applies, and is set, then the partition gets a VMC virtual I/O device in its device tree regardless of its partition definition (Override to include VMC is activated). If the Alpha flag applies, and is not set, then the partition does not get a VMC virtual I/O device in its device tree regardless of its partition definition (Override to remove VMC is activated) and it gets all the physical I/O resources in its device tree regardless of its partition definition (Override to include all physical I/O is activated). Note this condition requires that any other platform partitions be terminated. Given that the Ignore policy bit is off and the partition continues to run, the options and values presented in by this option vector and supported/chosen by the platform firmware are reported in the “ibm,architecture-vec-5” property of the /chosen node. Option vector number 1 “PowerPC Server Processor Architecture Level” and the property that reports the chosen value (i.e., “cpu-version”) represent the operational base architectural level of the processors -- that is without regard to enabled processor architectural options. Option vector number 3 “IBM PowerPC Server Processor Extensions” and option specific properties that report the chosen values represent the active processor architectural options. Some processor implementations may not support all combinations of these two option vectors. The firmware shall activate the highest level of processor support, consistent with partition attributes, that does not exceed the most restrictive of the two option vectors. Note the Cessation Policy bit may allow operation where the lowest level of processor support still exceeds the most restrictive case. If a client program does not support logical partitioning no other client programs may be running simultaneously on the platform. The platform may impose further restrictions beyond the scope of LoPAR. If the platform honors the client program restriction of not supporting logical partitioning, upon return the logical real address equals the platform real address. If the platform can not honor the restriction, the processing terminates as with a boot failure. The cessation policy option vector bit has no effect upon logical partitioning option vector bit.

ROM Node(s) The ROM Node(s), when present to represent optional platform read only memory containing directly executable platform firmware, shall be a child or children of the root node.

ROM Node Properties Each ROM Node shall have the following properties: “name” [S] Standard property name that denotes a ROM Node. prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be “rom”. “reg” [S] Standard property name to define a unit-address for the node. prop-encoded-array: One ( phys-addr, size) pair. The phys-addr of this property shall be the starting physical address of this ROM and the size value shall be 0. The size =0 prevents a conflict with the “reg” of this node’s children. “#address-cells” [S] Standard property name to define the address space representation of child nodes. prop-encoded-array: an integer, encoded as with encode-int. Its value shall be identical to that of this node’s parent’s “#address-cells” value. “ranges” [S] Standard property name to define the address range that is decoded by this /rom node. prop-encoded-array: One ( child-phys, parent-phys, size) triple, where child-phys equals parent-phys and the number of cells of each corresponds to the parent’s “#address-cells” value. “available” [S] Standard property name to define available ROM resources. prop-encoded-array: Arbitrary number of phys-addr, size pairs. Phys- addr is a phys.hi...phys.lo list of integers, each integer encoded as with encode-int. Size is one or more integers, each encoded as with encode-int. The value of this property defines resources, managed by this package, that are currently available for use by a client program. “write-characteristic” [S] Standard property name defines the ROM Technology. prop-encoded-array: a string, encoded as with encode-string, where the value could equal “flash”, “eeprom”, “rom” or “nvram”. “cacheable” [S] OF standard property indicating that the ROM is cacheable. prop-encoded-array: <none>. The presence of this property indicates that the ROM is cacheable.

ROM Node Methods If one or more ROM nodes are present, they shall each implement the following standard methods per , Section 3.6.1. The “reg” property is used to determine which ROM the standard methods apply to for multiple ROM’s. The following methods must be defined by /rom node. open (-- true) [M] Standard method to prepare the ROM Node for subsequent use. close (--) [M] Standard method to close the previously opened ROM Node. decode-unit (addr len -- phys.lo...phys.hi) [M] Standard method to convert text unit-string to physical address. encode-unit (phys.lo...phys.hi -- unit-str unit-len) [M] Standard method to convert physical address to text unit-string. probe (--) [M] OF method used at boot time to probe all ROM’s. The probe method for ROM Nodes shall probe for FCode images within the address space defined by its “reg” property as defined herein. For each page within its address space, look for a valid FCode image. A valid FCode image is defined to start with an FCode-header (see section 5.2.2.5 in ) where the first byte is start1, the format byte is 0x08, the length field indicates that the FCode program is contained within the address space of the /rom node, and where the checksum is correct. (This probing must take into account the possibility that the ROM image is in the opposite endian-ness from which OF is currently running.) If such an FCode image is found, a new child node shall be created by executing new-device and set-args, the FCode image copied to memory (taking into account the endian-ness) and the copy evaluated with byte-load. (The FCode program can use my-unit to create its “reg” property.). The arguments used by set-args are defined to be 0,0,unit-str, unit-len where unit-str is a text string representation of the physical address location for the FCode Image and unit-len is the length of the FCode Image.

ROM Child Node(s) This section describes the properties and methods for a ROM Child Node.

ROM Child Node Properties The following properties must be created by /rom child nodes. “name” [S] Standard property name that denotes a ROM child node. prop-encoded-array: A string, encoded as with encode-string. Some physical ROM implementations may not fully decode their entire address range. This could lead to multiple images of the ROM to appear at different addresses, due to the “aliasing” of the ROM image. To prevent multiple device nodes from appearing in the device tree, the FCode for such ROMs should look for an already existing peer node that represents their image. This could be done, for example, by checking that any of the peer of the child of its parent node has a “name” property value that is the same as this node’s FCode would create. If such a node is found, the FCode should “abort” the evaluation of its FCode (e.g., by executing an end0) before creating its “name” property. OF shall remove a node when the FCode evaluation for the node does not result in a “name” property being defined. “reg” [S] Standard property name that defines the child node address range for a ROM image(s). prop-encoded-array: List of ( phys-addr, size) specifications. Phys-addr is encoded as with encode-phys, and size is encoded as with encode-int. The phys-addr is a base address of the ROM image and size is the length of the ROM image.

ROM Child Node Methods The following methods must be defined by /rom child nodes. open (-- true) [M] Standard method to prepare this device for subsequent use. The open method must be prepared to parse my-args for the case(s) when the node is being opened in order to access “files”; e.g., when the bootinfo.txt file is being accessed during the multiboot menu. close (--) [M] Standard method to close the previously opened device. load (addr -- len) [M] Standard method to load an image. The image must be one that is recognized by the OF init-program method. It is strongly recommended that the ELF format be used, since it has the mechanism to specify configuration variable requirements of an OS.

Run Time Abstraction Services (RTAS) Node This system node is a child of “/” (root). This section defines properties and methods for the RTAS node. The RTAS Node shall not have “reg” or “ranges” properties.

RTAS Node Properties This section describes the rtas node properties. “name” [S] Standard property name that denotes the RTAS node. prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be “rtas”. “rtas-event-scan-rate” [S] property name that is the rate at which an OS should read indicator/sensor/error data prop-encoded-array: An integer, encoded as with encode-int The value of this property shall be a number indicating the desired rate for reading sensors and/or error information in calls per minute. This number is platform dependent. “rtas-indicators” [S] property name that indicates indicators are implemented. prop-encoded-array: An array of paired integers ( token maxindex), each encoded as with encode-int. The values for this property is a list of integers that are the token values ( token) for the defined indicators and the number of indicators ( maxindex) for that token which are implemented (see ) on the platform. Note: The indicator indices for a given token are numbered 0... maxindex-1. “rtas-sensors” [S] property name that indicates sensors are implemented. prop-encoded-array: An array of paired integers ( token maxindex), each encoded as with encode-int. The values for this property is a list of integers that are the token values ( token) for the defined sensors and the number of sensors ( maxindex) for that token which are implemented (see ) on the platform. Note: The sensor indices for a given token are numbered 0 ... maxindex-1. “rtas-version” [S] property name describes version information for the RTAS implementation. prop-encoded-array: An integer, encoded as with encode-int. The value of this property shall denote the version the RTAS implementation. For this version, the integer shall be as defined in this architecture. “rtas-size” [S] property name is the size of the RTAS memory image. prop-encoded-array: An integer, encoded as with encode-int. The value of this property shall be the amount of contiguous real system memory required by RTAS, in bytes. “rtas-display-device” [S] property name identifies RTAS Display Device prop-encoded-array: An integer, encoded as with encode-int. The value of this property shall be the phandle of the device node used by the RTAS display-character function. “rtas-error-log-max” [S] property name identifies maximum size of an extended error log entry. prop-encoded-array: An integer, encoded as with encode-int. The value of this property shall be the maximum size of an extended error log entry, in bytes. “power-on-max-latency” [S] property name specifies a future power on time capability. prop-encoded-array: An integer, encoded as with encode-int. The value of this property specifies the capability of the hardware to control the delay of system power on in days. If the property is present, the value shall indicate the maximum delay or latency in days. If the property is not present, the maximum delay or latency is 28 days. “ibm,preserved-storage” property name specifies that the client program was loaded with one or more LMBs preserved from a previous client program. prop-encoded-array: None, this is a name only property. The client program may wish to save the contents of the preserved LMBs and deregister the LMBs for preservation. “ibm,scan-log-directory” property name specifies that the platform supports the scan-log directory option. prop-encoded-array: None, this is a name only property. “ibm,indicator-<token>” property name to provide a FRU location code for identifying each indicator. prop-encoded-array: an array of maxindex + 1 strings, encoded as with encode-string. “ibm,sensor-<token>” property name to provide a FRU location code for identifying each physical sensor. prop-encoded-array: an array of maxindex + 1 strings, encoded as with encode-string. “ibm,display-line-length” property name to provide the length of a display line in number of characters. prop-encoded-array: an integer, encoded as with encode-int. “ibm,display-number-of-lines” property name to provide the number of lines in the display. prop-encoded-array: an integer, encoded as with encode-int. “ibm,display-truncation-length” property name, when provided, specifies the length to which each line to be display is truncated, based on which line of the physical display on which the line is displayed. When the truncation length is greater than the length specified in the “ibm,display-line-length” property, then the platform provides a platform-dependent method of displaying the line to the user. prop-encoded-array: An array of integers, each encoded as with encode-int. The number of integers corresponds to the number of lines, as defined by the “ibm,display-number-lines” property. The first integer refers to the truncation length for the first physical line of the display, the second to the second physical line, and so on. “ibm,form-feed” property name to provide an indication of the form-feed capability. prop-encoded-array: a character, NULL (0x00) if form-feed is not supported and np (0x0C) if form-feed is supported, encoded as with encode-int. “ibm,environmental-sensors” property name describes the environmental sensors which are available to an application. prop-encoded-array: An array of paired integers (token maxindex), each encoded as with encode-int. “ibm,flash-block-version” property name in the /rtas node indicates the block list format to be used. prop-encoded-array: integer encoded as with encode-int. Value is 0x01 for the discontiguous block list. (If a new version of the block list is ever required, other values could be defined.) “ibm,errinjct-tokens” [S] property name defines the error inject functions implemented on this platform. prop-encoded-array: List of (errinjct-token-name, errinjct-token-value) specifications. errinjct-token-name: A string, encoded as with encode-string. errinjct-token-value: is encoded as with encode-int. “ibm,lrdr-capacity” property name in the /rtas node identifies the dynamic reconfiguration capabilities of the partition prop-encoded-array: A triple consisting of phys, size, and one integer encoded as with encode-int The phys (of size #address-cells) communicates the maximum address in bytes and therefore, the most memory that can be allocated to this partition. The size (of size #size-cells) communicates the increment (quantum of logical memory dynamic reconfiguration). The first integer communicates the maximum number of processors (implied quantum of 1). Note: Some implementations depend upon the presence and value of a second integer. Future extensions to this property should not define a second integer for new purposes. “ibm,hypertas-functions” property name of the /rtas node, defines the platform’s implemented hypervisor RTAS function sets. prop-encoded-array: List of Hypervisor-RTAS-function-set specifications. Each Hypervisor-RTAS-function-set specification is a byte string encoded as with encode-string. “ibm,dma-delay-time” property name to define the time delay need to ensure outstanding DMA operations targeting migrated pages have completed. prop-encoded-array: A one cell integer encoded as with encode-int that represents the number of micro-seconds that the OS should wait prior to reusing migrated DMA read target pages. “ibm,associativity-reference-points” [S] property name to define the associativity reference points for the “ibm,associativity” properties of this platform. prop-encoded-array: A list of one or more integers cell(s) encoded as with encode-int. “ibm,max-associativity-domains” property name to define the maximum number associativity domains for this platform. prop-encoded-array: An associativity list such that all values are the maximum that the platform supports in that location. The associativity list consisting of a number of entries integer (N) encoded as with encode-int followed by N integers encoded as with encode-int each representing maximum number associativity domains the platform supports at that level. “ibm,request-partition-shutdown” property name to specify that the partition was rebooted in the forced fire hose dump mode. prop-encoded-array: An integer encoded as with encode-int that represents the platform’s partition shutdown configuration variable. The defined states are: 0 = The platform boots with no request to save appropriate data nor shutdown the partition. 1 = The platform boots with a conditional request to save appropriate data and shutdown the partition. The client program should check for an EPOW sensor state of 3 and if present, it should save appropriate data and shutdown the partition. If the EPOW sensor state of 3 is not present, then the partition should initiate a reboot since the device tree will be incomplete. 2 = The platform boots with a mandatory request to the client program to save appropriate data and shutdown the partition. “ibm,integrated-stop-self” property name indicating that prior to placing a processor in the stopped state, the platform flushes and disables any caches/memory exclusively used by the issuing processor. prop-encoded-array: NULL “ibm,rks-hcalls” property name: indicating the hcalls that are implemented with a reduced kill set. Absence of this property indicates that only hcalls that are specified as always having a reduced kill set provide that semantic. prop-encoded-array: A one to N byte bit vector, bit positions representing hcall()s (see ) that present a reduced kill set per their architectural specification. <emphasis role="bold"><literal>“ibm,rks-hcalls”</literal></emphasis> bit vector to hcall map Byte Number Bit Number hcall 0 0 0b11 for H_CONFER & H_PROD 1 2 Set to 1 if H_PURR is implemented with a reduced volatile kill set of r3 & r4; else set to 0. 3 Reserved for future expansion (0b0) 4 5 6 7 1-N Reserved for future expansion

“ibm,reset-capabilities” property name indicates what capabilities the platform supports relative to the ibm,set-slot-reset RTAS call, when that RTAS call is implemented. prop-encoded-array: An integer encoded as with encode-int that represents the functions supported in the ibm,set-slot-reset RTAS call 0 = Platform supports Functions 0 and 1 supported. 1 = Platform supports Functions 0, 1, and 3. Note: The absence of this property implies the platform supports Functions 0 and 1 for the ibm,set-slot-reset RTAS call, when that RTAS call is implemented. “ibm,configure-kernel-dump-sizes” property name specifies that the Platform Assisted Kernel Dump option is supported for sections described by this property. prop-encoded-array: For each dump section type supported, a 32 bit cell which defines the ID of a supported section followed by two 32-bit cells which gives the size of the section in bytes (not including any disk headers.) “ibm,configure-kernel-dump-version” property name specifies that the Platform Assisted Kernel Dump option is supported for versions described by this property. prop-encoded-array: Contains a 16-bit cell describing the minimum kernel dump version supported by the firmware followed by a 16-bit cell describing the maximum kernel dump version supported by the firmware. “ibm,kernel-dump” property name specifies the presence of a registered kernel dump in the Platform Assisted Kernel Dump option. prop-encoded-array: Contains the description of the registered kernel dump in the format described in . “ibm,read-slot-reset-state-functions” property name specifies the implementation of certain input or output fields in the ibm,read-slot-reset-state2 RTAS call. If this property does not exist, then the ibm,read-slot-reset-state2 RTAS call implements only the first 3 inputs and the first 4 outputs ( Number Inputs is required to be 3 and the Number Outputs is required to be 4), as defined in . prop-encoded-array: Contains a 32 bit cell, with the bits defined as follows: Bits 0-29: Reserved (value of 0). Bit 30: When a value of 1, the ibm,read-slot-reset-state2 RTAS call checks the Number Outputs and the implements the 5th output ( Number Outputs of 5), as defined by . Bit 31: When a value of 1, the ibm,read-slot-reset-state2 RTAS call implements the first 3 inputs and the first 4 outputs ( Number Inputs of 3 and the Number Outputs of 4), as defined in . This bit is always required to be a value of 1 when this property is implemented. “ibm,change-msix-capable” property name indicating the platform supports the ibm,change-msi RTAS call with Number of Outputs equal to 4 and Functions 3, 4, and 5. prop-encoded-array: <none>

<literal>/RTAS</literal> node DR Sensors and Indicators The following sensors and indicators are defined for the /RTAS node for the DR option. “9003” sensor token, the existence of this token number denotes that the platform supports the 9003 “DR entity sense” sensor. “9001” indicator token, the existence of this token number denotes that the platform supports the 9001 “isolation state” indicator. “9002” indicator token, the existence of this token number denotes that the platform supports the 9002 “dr-indicator” indicator used to guide operators in the physical add or removal of hardware. “9003” indicator token, the existence of this token number denotes that the platform supports the 9003 “allocation-state” indicator. “ibm,extended-os-term” property-name indicating that the platform supports extended ibm,os-term behavior as described in . prop-encoded-array: encode-null

RTAS Function Property Names This section defines the property names associated with the various RTAS functions defined by . should be used as the reference for RTAS Functions currently implemented. Each RTAS function that a platform implements shall be represented by its own function property, who’s value is the token used to invoke the function on an RTAS call. The formal property definition for each such property is of the form: property name specifies the name of the RTAS function -- such as: “nvram-fetch” [S] prop-encoded-array: The value, token, is an integer encoded as with encode-int. If an RTAS function is implemented, there is a property name which corresponds to its function name. The value of this property is a token. This token, when passed to RTAS via its rtas-call interface (see below), invokes the named RTAS function. If a RTAS function is not implemented, there will not be a property corresponding to that function name. See the for more information about RTAS functions. “ibm,termno” property name of the /rtas node defines the virtual terminal numbers available for use by this partition. prop-encoded-array: A pair of integers encoded as with encode-int, the first being the value of the lowest termno in a contiguous range of supported values, the second being the number of termno values supported. Note: The number of supported termno values is implementation dependent -- the minimum number is one. “ibm,hypertas_functions” property name of the /RTAS node, defines the platform’s implemented hypervisor RTAS function sets. prop-encoded-array: List of Hypervisor-RTAS-function-set specifications. Each Hypervisor-RTAS-function-set specification is a byte string encoded as with encode-string.

RTAS Node Methods The instantiate-rtas or instantiate-rtas-64 method is invoked by the OS to instantiate the RTAS functionality. This is accomplished via the call-method Client Interface Service. If the platform supports the ibm,client-architecture-support root node method, and that method has not been called prior to the call of the instantiate-rtas or instantiate-rtas-64 methods, then the platform shall operate at the least functional level supported by the platform. Note: Platforms should provide a manual override capability to allow most functional level allowed by the partition configuration in the event that a client program does not call the ibm,client-architecture-support root node method prior to the instantiation of RTAS. instantiate-rtas (rtas-base-address -- rtas-call) [M] Invoking the instantiate-rtas method binds the RTAS environment to a given location in System Memory and initializes the RTAS environment. The in parameter, rtas-base-address, is the physical address to which the RTAS environment is to be bound. This call indicates that RTAS is instantiated in a 32-bit mode. The amount of contiguous real memory that should be allocated for the RTAS environment is given by the value of the “rtas-size” property. Upon completion of the instantiate-rtas method, an entry point address, rtas-call, is returned. The value of rtas-call specifies the physical address of the entry point into RTAS for future RTAS function calls. instantiate-rtas-64 (rtas-base-address -- rtas-call) [M] Invoking the optional instantiate-rtas-64 method binds the RTAS environment to a given location in System Memory and initializes the RTAS environment. The in parameter, rtas-base-address, is the physical address to which the RTAS environment is to be bound. This call indicates that RTAS is instantiated in a 64-bit mode. The amount of contiguous real memory that should be allocated for the RTAS environment is given by the value of the “rtas-size” property. Upon completion of the instantiate-rtas-64 method, an entry point address, rtas-call, is returned. The value of rtas-call specifies the physical address of the entry point into RTAS for future RTAS function calls.

Properties of the Node of type cpu When the platform implements the LPAR option the following properties are required of the /cpus node ibm,pft-size property name of the children of type “cpu” of the /cpus node, defines the size of the processor’s page frame table. prop-encoded-array: A pair of integers encoded as with encode-int, the first being the NUMA CEC Cookie (up to a maximum of (2 16)-1) the second being the base 2 log of the size of the page frame table in bytes. Notes: On single CEC platforms, the NUMA CEC Cookie value is zero. Due to constraints caused by initial memory allocations, and other running partitions, the firmware may not be able to allocate a node’s PFT for the full size requested in the PFT_size configuration variable. The “ibm,pft-size” property of course reflects the actual size allocated. The partitions running on multiple NUMA nodes would have multiple PFTs which did not look alike due to the difference in mapping local and remote page frames.) To support dynamic addition and removal of processors, the /cpus node contains either the ibm,drc-info property or the following set of four properties: ibm,drc-types (cpu), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have entries for the maximum number of dynamically reconfigurable processors that the platform supports for the specific OS image. “ibm,ppc-interrupt-server#s” [S] property name: Defines the single processor server numbers associated with this processor. Placing the numerical equivalent of one of these quantities into the server# field of an XIVR directs associated interrupts to this processor. The first server number is associated with the “primary processor thread” any subsequent numbers are associated with the secondary. etc. hardware threads that the processor may implement. prop-encoded-array: A list of one or more integers in the range of 0 to 2“ibm,interrupt-server#-size” encoded as with encode-int. Note: In order to achieve optimal performance, processor server numbers should be activated in the order that they are presented in the “ibm,ppc-interrupt-server#s” property and deactivated in the reverse order. “ibm,ppc-interrupt-gserver#s” [S] property name: Defines the multiple processor global server numbers to which this processor belongs. Placing the numerical equivalent of one of these quantities into the server# field of an XIVR directs associated interrupts to one of the processors in that group. prop-encoded-array: A list of ( server#, gserver#s) specification pairs. the first integer specifies a single processor server# as presented in the node’s “ibm,ppc-interrupt-server#s” property, followed by an integer with a value less than or equal to 2 “ibm,interrupt-server#-size” encoded as with encode-int that specifies the global server queue that also may present interrupts to the interrupt management area associated with the server#. “ibm,sub-processors” property name: the sub-processor configuration that is running on this processor. In the absence of this property, this processor may not be divided into sub-processors. prop-encoded-array: a series of three or more integers each encoded as with encode-int. The value of the first integer indicates how many integers follow (the value 2 indicates that two integers follow). The second integer indicates the number of sub-processors that are running on this processor. If the processor is not divided into sub-processors the value of the second integer shall be 1, two sub-processors shall be represented by the value 2, four sub-processors shall be represented by the value 4 and so on. The third integer indicates the maximum number of sub-processors that could be configured to run on this processor. Client programs shall ignore subsequent integers beyond those defined at the time they were written.

Extensions for LoPAR I/O Sub-Systems LoPAR I/O sub-system events may be signaled in a variety of ways depending upon platform capabilities. In order of increasing functionality: Events are universally fatal, and are signaled via checkstop. After being enabled, the effected section enters freeze state signalling this state with a return of all 1’s to any MMIO load instruction (If not enabled functionality of the specific section reverts to #1. Presence of ibm,set-eeh-option RTAS call denotes platforms that support this level of functionality.) An extension to #2 above wherein, after being enabled for a specific section of the I/O sub-system, additional event conditions may be reported and events are signaled using an external interrupt. The platform’s capability to support this level of functionality is reported by the inclusion of the “ibm,i/o-events-capable” property (see definition below) in nodes where enabling control may be exercised. “ibm,i/o-events-capable” property name indicating that I/O sub-system events detected by the hardware represented by this node in the device tree may be singled with an I/O event interrupt if enabled. prop-encoded-array: 0 to N interrupt specifiers (per the definition of interrupt specifiers for the node’s interrupt parent). When no interrupt specifiers are present, then the interrupt, if enabled, is signaled via the interrupt specifier given in the I/O-events child node of the /events node. To perform certain management functions, it is necessary to quiesce segments of the platform’s I/O infrastructure, such quiescence domains are not representable by a strict tree structure. The “ibm,io-quiesce-domains” property relates the membership of the various elements of a platform’s I/O sub-system to such quiescence domains. “ibm,io-quiesce-domains” property name indicating the I/O quiesce domains of which this device, and all devices under this device (if any), is a member. prop-encoded-array: List of one or more domain-id’s to which this device belongs, and to which all devices under this device (if any) belongs. Domain-id's are encoded as with encode-int. Virtual I/O that does not take up physical address locations is represented in a device sub tree for which the “#size-cells” and “#address-cells” properties are zero and one, respectively. However, the ibm dma-window properties, such as “ibm,dma-window” and “ibm,my-dma-window”, need to contain real size and address fields. The number of cells for these real size and address fields need to be non-zero. “ibm,#dma-size-cells” property name to define the package’s dma address size format. prop-encoded-array: number encoded as with encode-int. The property value specifies the number of cells that are used to encode the size field of ibm dma-window properties. If the “ibm,#dma-size-cells” property is missing, the default value is the “#size-cells” property for the package. If both the “ibm,#dma-size-cells” and “#size-cells” properties are missing, refer to the “#size-cells” property definition in the for the default value. “ibm,#dma-address-cells” property name to define the package’s dma address format. prop-encoded-array: number encoded as with encode-int. The property value specifies the number of cells that are used to encode the physical address field of ibm dma-window properties. If the “ibm,#dma-address-cells” property is missing, the default value is the “#address-cells” property for the package. If both the “ibm,#dma-address-cells” and “#address-cells” properties are missing, refer to the “#address-cells” property definition in the for the default value.

PCI Host Bridge Nodes This section describes the PCI Host Bridge (PHB) properties which are added or modified for an LoPAR implementation. Refer to for the base PCI properties and methods. For each platform PCI Host Bridge, a “reg” property shall be present in the respective PCI Node. Note: Since the standard RTAS PCI configuration access services do not have separate arguments identifying the PCI host bridge to which a service applies, platforms with multiple PCI host bridges must assign them unique bus numbers. An OS must not reassign bus numbers if it expects to make subsequent use of the any RTAS PCI configuration access services. To support dynamic addition and removal of PHBs, the / node contains either the ibm,drc-info property or the following set of four properties: ibm,drc-types (phb), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have entries for the maximum number of dynamically reconfigurable PHBs that the platform supports for the specific OS image.

PCI Host Bridge Properties For each PHB in the platform (called a PCI Bus Controller in the PCI Bus binding), a PCI Host Bridge Node shall be defined as a child node of the system bus, in accordance with . Each PCI PHB Node shall have a Unit Address defined in the “reg” property that is unique and persistent from each boot-to-boot. One way for the platform to meet this requirement is to supply a virtual Unit Address based upon a unique identifier stored in the hardware. In this case, the size field of the first “reg” property phys-address, size pair shall be zero. The following properties are modified or added by this architecture and shall apply to each of these nodes. Each PHB shall also have the “used-by-rtas” property, since RTAS is used for PCI Configuration. “ranges” [S] Standard property name defines this PHB’s physical address ranges. prop-encoded-array: Two or more ( child-phys, parent-phys, size) specifications. This property is mandatory for PCI Host Bridges in LoPAR implementations. The property value consists of four ( child-phys, parent-phys, size) specifications, as described in . The first specification shall specify the configured address and size of this PHB’s I/O Space. (I/O Space is shown as “BIOn” to “TIOn” in "Address Map" section.) The second specification shall specify the configured address and size of this PHB’s Memory Space. (Memory Space is shown as “BPMn” to “TPMn” in the Common Hardware Reference Platform Architecture.) “model” [S] Standard property name indicating this PHB’s manufacturer, part number, and revision level. This property shall be present if this PHB does not supply the following standard PCI configuration properties which represent the values of standard PCI configuration registers: “vendor-id”, “device-id”, and “revision-id”. prop-encoded-array: Text string, encoded as with encode-string. The value of this property is a vendor dependent string which uniquely identifies this PHB and is correlated to its manufacturer, part number, and revision level. (see for more information.) The string value is device dependent, but shall supply information sufficient to identify the part to a level equivalent to the level achievable via the standard PCI configuration registers: “vendor-id”, “device-id”, and “revision-id”. “64-bit-addressing” [S] property name indicates this PHB’s capability to address more than 4 GB of memory. prop-encoded-array: <none> This property shall be present indicating that the PHB supports addressing more than 4 GB of memory (required for all PHB nodes). “external-control” [S] property name indicates this PHB’s ability to support the PA external control facility. prop-encoded-int: List of integers, each encoded as with encode-int. The property value, if present, is a list of Resource ID’s the version of the PA external control facility supports. This property shall be present if this PHB supports the PA external control facility, otherwise the property shall be absent. “ibm,tce-alloc-info” property name indicates the addresses of platform pre allocated TCE table space. prop-encoded-array: One to N phys-addr, size pair(s). The first pair represents the memory area allocated by the platform for the TCE tables associated with this PHB. Any subsequent pairs represent memory areas that the OS should avoid using to minimize performance impacts. Phys-addr is encoded as with encode-phys the number of cells for phys corresponds to “#address-cells” value applicable to this node. size the number of cells for size corresponds to the “#cell-size” value applicable to this node. “ibm,max-completion-latency” property name indicates the maximum DMA Read completion latency for IOAs under this PHB. prop-encoded-array: Integer, encoded as with encode-int. This property, when present (for example, see Requirement ), indicates the maximum DMA Read completion latency for IOAs under this PHB, in microseconds. For plug-in adapters, the latency value does not include latency of any additional PCI fabric (for example, PCI Express switches) on the plug-in adapter. “ibm,extended-address” [S] property name indicates this platform supports Peripheral Memory Spaces, Peripheral I/O Spaces, and SCA spaces above 4 GB. prop-encoded-array: <none> This property must be present in all PHB nodes. “ibm,pcie-link-width-stats” property name indicates the collection of PCI Express link-width capabilities and measurements at the PE below the PHB. prop-encoded-array: 2 integers encoded with encode-int The first integer represents the maximum PCI Express lane-width at the Partitionable Endpoint. The second integer represents the actual PCI Express lane-width at the Partitionable Endpoint. Implementation Note: In some cases, a PCIe device may train at a different width depending on the speed capabilities of the link. “ibm,pcie-link-speed-stats” property name indicates the collection of PCI Express link-speed capabilities and measurements at the PE below the PHB. prop-encoded-array: 2 integers encoded with encode-int. The value of each integer is based on which bit is set to reflect link speed according to the Supported Link Speed Vector segment of the Link Capabilities 2 Register as defined in the PCI Express Capability Structure chapter of the . In the 3.0 version of that specification, the supported values are 0x1 (bit 0) = 2.5 GT/s, 0x2 (bit 1) = 5.0 GT/s, and 0x4 (bit 2) = 8.0 GT/s. “ibm,max-rtce-mappings” property name: for platforms that support the hcall-migrate function set and more than a single Redirected RDMA mapping per virtual TCE, this property indicates that there are limits to the number if such multiple Redirected RDMA mappings when used by children of this PHB as indicated by the property value. prop-encoded-array: Maximum number of Redirected RTCE mappings encoded as with encode-int.

Properties for Children of PCI Host Bridges The following properties are defined for PCI host bridges and their children. “133mhz-capable” [S] property name: The presence of this property indicates the device’s capability of operating at 133 megahertz. Only present if PCI-X Status Register bit 17 is set. prop-encoded-array: None. “266mhz-capable” [S] property name: The presence of this property indicates the device’s capability of operating at 266 megahertz. Only present if PCI-X Status Register bit 30 is set. prop-encoded-array: None. “533mhz-capable” [S] property name: The presence of this property indicates the device’s capability of operating at 533 megahertz. Only present if PCI-X Status Register bit 31 is set. prop-encoded-array: None. “ibm,msi-ranges” property name: Defines the Message Signaled Interrupt interrupt source number (as returned by H_XIRR) range(s) assigned to this unit using the MSI capability structure. (Note this property is only supplied if the package is assigned one or more message signaled interrupt numbers at boot time using the MSI capability structure, those packages assigned level sensitive interrupts include the standard interrupts property.) The platform firmware assigns the interrupt source numbers in order to the first N Message Signaled Interrupt configuration spaces of the adapter, setting the associated configuration spaces, in accordance with the platform's hardware configuration, to produce the interrupt source numbers specified. prop-encoded-array: List of one or more (int-number, range) specifications. Int-number is the first interrupt source number in a contiguous range of interrupt source numbers encoded as with encode-int. Range is the one based count of consecutive interrupt source numbers that compose the specified range of interrupt source numbers, encoded as with encode-int. “ibm,msi-x-ranges” property name defines the Message Signaled Interrupt interrupt source number (as returned by H_XIRR) range(s) assigned to this IOA function using the MSI-X capability structure. (Note this property is only supplied if the package is assigned one or more message signaled interrupt numbers at boot time using MSI-X capability structure, those packages assigned level sensitive interrupts include the standard interrupts property.) The platform firmware assigns the interrupt source numbers in order to the first N MSI-X vectors of the IOA function, setting the associated configuration spaces and MSI-X vectors, in accordance with the platform's hardware configuration, to produce the interrupt source numbers specified. prop-encoded-array: List of one or more (int-number, range) specifications. Int-number is the first interrupt source number in a contiguous range of interrupt source numbers encoded as with encode-int. Range is the one based count of consecutive interrupt source numbers that compose the specified range of interrupt source numbers, encoded as with encode-int. “ibm,req#msi” property name: Defines the number of Message Signaled Interrupts requested by the adapter as communicated in its MSI capability structure. This number may be greater than the number of Message Signaled Interrupts actually assigned by the firmware. prop-encoded-array: number of requested interrupts encoded as with encode-int. “ibm,req#msi-x” property name: Defines the number of MSI-X Interrupts requested by the adapter as communicated in the Table Size field of the MSI-X Capability Structure for the adapter. This number may be greater than the number of MSI-X interrupts actually assigned by the firmware. prop-encoded-array: number of requested MSI-X interrupts encoded as with encode-int. “ibm,connector-type” property name to identify the connectors associated with a built-in IOA that supports wrap test. This property must be provided if there is more than one connector for the same IOA on the platform. prop-encoded-array: the concatenation, with encode+, of an arbitrary number of text strings, each encoded as with encode-string. “ibm,wrap-plug-pn” property name to provide the part number(s) of the wrap plug(s) required for testing built-in IOAs with the default connector or the connectors specified in “ibm,connector-type”. If this property is provided in the same node with an “ibm,connector-type” property, there is a one-to-one correspondence between the strings in each property. If this property is provided without an “ibm,connector-type” property, there is assumed to be only one connector for the device (default connector) and this property should contain only one string. If multiple wrap plugs may be used with the same connector, their part numbers shall be represented in the same string, separated by commas. prop-encoded-array: the concatenation, with encode+, of an arbitrary number of text strings, each encoded as with encode-string. “ibm,pci-config-space-type” property name: Indicates if the platform supports access to an extended configuration address space from the PHB up to and including this node. 0 = Platform supports only an eight bit register number for configuration address space accesses. 1 = Platform supports a twelve bit register number for configuration address space accesses. This property may be provided in all PHB nodes and their children. Note: The absence of this property implies the platform supports only an eight bit register number for configuration address space accesses. “ibm,reserved-explanation” property name indicates why this PHB's “status” property contains the value of “reserved” or “reserved-uninitialized”. prop-encoded-array: Text string, encoded as with encode-string. The property value, when present, can have the values specified in . Values <emphasis role="bold"><literal>“ibm,reserved-explanation”</literal></emphasis> Value Explanation storage-system-io Reserved for storage system product use pcix-over-pcie PCIe device is abstracted as a PCIx device in the device tree for legacy compatibility

“ibm,pe-total-#msi” property name defines the maximum number of Message Signaled Interrupts (MSI plus MSI-X) that are available to the PE below this device tree node. This number only indicates the number of available interrupts, not the number assigned. The number assigned for an IOA may be obtained by Function 0 (Query only) of the ibm,change-msi RTAS call. prop-encoded-array: Maximum number of interrupts encoded as with encode-int. “ibm,ehci-boot-supported” property name: indicates if this IOA function for USB 2.0 (EHCI) supports devices beneath it to be used for boot. prop-encoded-array: None. “ibm,pe-reset-is-flr” property name: The presence of this property in the PCI Express function’s OF Device Tree node indicates that the platform will use the Function Level Reset (FLR) of the function to reset the function when the ibm,set-slot-reset RTAS call is used to reset the PE, and not the PCI Express Hot Reset. prop-encoded-array: None. “ibm,ddw-applicable” property name: The Dynamic DMA Windows option RTAS calls may be used against the PE below this node. prop-encoded-array: A list of three integers encoded as with encode-int. This property may be provided in all PHB nodes or bridge nodes that are the PHB’s children. Separate properties must exist for each PE that can participate in the DDW option (exists in the node above the PE). The existence of this property in any node, indicates that the platform supports the Dynamic DMA Windows option for the platform and for the PE below that node. Lack of this property in the bridge node above a PE indicates that the DDW option RTAS calls are not applicable to that PE. The values in the property are defined as follows: The first integer represents the token to be used for the ibm,query-pe-dma-window RTAS call. The second integer represents the token to be used for the ibm,create-pe-dma-window RTAS call. The third integer represents the token to be used for the ibm,remove-pe-dma-window RTAS call. “ibm,ddw-extensions” property name: Extensions to the Dynamic DMA Windows option RTAS calls may be used against the PE below this node. prop-encoded-array: A list of integers encoded as with encode-int. This property may be provided in all PHB nodes or bridge nodes that are the PHB’s children. Separate properties shall exist for each PE that can participate in the extensions to the DDW option (exists in the node above the PE). The existence of this property in any node, indicates that the platform supports the extensions to the Dynamic DMA Windows option for the platform and for the PE below that node. Lack of this property in the bridge node above a PE indicates that the extensions of the DDW option RTAS calls are not applicable to that PE. This property is designed to be extended in the future by adding integers to the end of the list, reading software should be prepared to handle earlier versions of the property that will have a short list as well as ignore longer lists from later versions than it was designed to handle. The values in the property are defined as follows: The first integer represents the number of extensions implemented. Subsequent integers represent values associated with each extension such as a token for an additional RTAS call or an architectural level of an extended interface. The value of one indicates that only a single extension is implemented as specified by the second integer in the list. provides the definition of the subsequent integers as defined for the LoPAR level of the DDW option. ibm,h-get-dma-xlates-supported property name: to identify those PHBs for which H_GET_DMA_XLATES is supported on all child LIOBNs. prop-encoded-array: <none> ibm,h-get-dma-xlates-limited-supported property name: to identify those PHBs for which H_GET_DMA_XLATES_LIMITED is supported on all child LIOBNs. prop-encoded-array: <none>

LPAR Option Properties “ibm,dma-window” property name to define the bus address window children of this bridge may use for dma. prop-encoded-array: One ( logical-bus-number, phys, size) triple where the logical bus number (LIOBN) is a one cell cookie representing the unique range of TCE entries assigned to this bridge encoded as with encode-int, the number of cells for phys corresponds to the node’s “ibm,#dma-address-cells” value while the number of cells for size corresponds to the “ibm,#dma-size-cells” for this node. Implementation Note: Platforms that support PHB level granularity of IO assignment to partitions place the “ibm,dma-window” property in the PHB node, while platforms that support slot level granularity place the “ibm,dma-window” property in the bridge node that creates the per slot bus isolation. Note: The first element of the ibm,dma-window triple (the LIOBN) is used as a parameter to firmware DMA setup routines to identify the specific I/O address space (TCE table) to be referenced. “ibm,is-vf” property name to define that the node represents an I/O Virtualized instance of an I/O adapter. prop-encoded-array: A one cell value that represents the LoPAR architectural level of the virtualization: “<emphasis>ibm,is-vf</emphasis> ” Values Value: Description: 0 Not used 1 Per LoPAR All others Reserved

Memory Node This section defines the LoPAR modifications to the OF / memory node. In LoPAR, the memory allocated to an OS image may be divided into a number of allocation units called “regions” or “Logical Memory Blocks (LMB). An OS image may be dynamically allocated additional regions or may be asked to release regions. Each LMB is either represented in the device tree by its own / memory node or by an entry in /ibm,dynamic-reconfiguration-memory nodes (see ). The / memory node that refers to the storage starting at real address zero ( “reg” property starting at the value zero) always remains allocated to an OS image. The client program is initially loaded into this storage, called the RMA, that is represented by the first value of the “reg” property of this first / memory node. Additional storage regions may each be represented by their own / memory node that includes dynamic reconfiguration (DR) properties or by an entry in /ibm,dynamic-reconfiguration-memory nodes. To support dynamic addition and removal of regions, the / node contains either the ibm,drc-info property or the following set of four properties: ibm,drc-types (MEM), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have entries for the maximum number of dynamically reconfigurable regions that the platform supports for the specific OS image.

Properties of the memory Node In addition to the standard properties defined for the /memory node, the following are required for each node representing a dynamically allocable memory region. Platforms that support the dynamic reconfiguration of memory regions represent each such logical memory block with its own /memory node. Any new memory granted to an OS image is done so with a new /memory node, and OS images may free memory only in full blocks represented by one of its currently held /memory nodes. The value of “#address-cells” for this node is 1. The value of “#size-cells” for this node is 0 because the children of this node do not consume any physical address space. The “ibm,my-drc-index” property as defined in . “ibm,preservable” property name that denotes the platform’s ability to preserve the contents of the storage represented by this node. prop-encoded-array: A integer encoded as with encode-int that represents the ability of the platform to preserve the contents of the storage. All non-negative values represents the expected length of time, in minutes, that the platform can sustain the state of the storage. A value of 0 indicates the storage is not preservable and the client program may not register this storage for preservation, this is the assumed state if the “preservable” property is not present. The largest positive number represents an indefinite retention time as provided by such technologies as flash storage. Negative values indicate that the storage is preservable as long as external power is maintained, perhaps by an external battery not directly integrated into the platform. “ibm,preserved” property name that denotes the preservation state of the contents of the storage represented by this node. prop-encoded-array: An integer encoded as with encode-int that represents the preservation state of the storage. The defined states are: 0= The storage was not registered for preservation and thus not preserved. This is the assumed state if the “preserved” property is not present. This is also the state if the platform has lost knowledge of the preservation registration state of the storage. 1= The storage was registered for preservation and is has been preserved since the client program last modified it. 2= The storage was registered for preservation, however, the contents have not been preserved. “ibm,expected#pages” property name that denotes the number of pages that the client program is expected to use to virtually map the LMB represented by this node. prop-encoded-array: An integer encoded as with encode-int that represents the log base 2 of the expected number of virtual pages that the client program will use to map the LMB represented by this node. “ibm,no-h-migrate-dma” property name that designates that the memory in the memory node in which this property resides cannot have the H_MIGRATE_DMA hcall() used against it. prop-encoded-value: <none> this is a name only property.

ibm,dynamic-reconfiguration-memory This device tree node defines an alternative means to represent a number of dynamically-reconfigurable logical memory blocks (LMBs). This node must only be generated by OF when instructed to do so by the client program in the ELF header. All memory which is not subject to dynamic reconfiguration (such as the RMA) is represented in /memory node(s). This node is a child of root. This node does not have a unit address or “reg” property. The following properties are defined. “ibm,lmb-size” property name that defines the size of each dynamically reconfigurable LMB. prop-encoded-array: An integer encoded as with encode-phys that represents the size in bytes of each LMB. “ibm,associativity-lookup-arrays” property name that defines a lookup array in which to find the ibm,associativity-array property value for the LMBs. prop-encoded-array: The number M of associativity lists encoded as with encode-int, the number N of entries per associativity list encoded as with encode-int, followed by M associativity lists each of length N integers encoded as with encode-int. This property is used to duplicate the function of the “ibm,associativity” property in a /memory node. Each “assigned” LMB represented has an index valued between 0 and M-1 which is used as in index into this table to select which associativity list to use for the LMB. “unassigned” LMBs are place holders for potential DLPAR additions, for which the associativity list index is meaningless and is given the reserved value of -1. This static property, need only contain values relevant for the LMBs presented in the “ibm,dynamicreconfiguration-memory” node; for a dynamic LPAR addition of a new LMB, the device tree fragment reported by the ibm,configure-connector RTAS function is a /memory node, with the inclusion of the “ibm,associativity” device tree property defined in . “ibm,dynamic-memory” property name that defines memory subject to dynamic reconfiguration. prop-encoded-array: The number N of LMB list entries defined at boot time, encoded as with encode-int, followed by N LMB list entries. An LMB list entry consists of the following elements. There is one LMB list entry per LMB represented. Logical address of the start of the LMB, encodes as with encode-phys. This corresponds to the first words in the “reg” property in a /memory device tree node. DRC index of the LMB, encoded as with encode-int. This corresponds to the “ibm,my-drc-index” property in a /memory device tree node. Four (4) bytes reserved for future expansion of flag. Associativity list index for the LMB, encoded as with encode-int. This is used as an index into “ibm,associativity-lookup-arrays” property defined above to retrieve the associativity list for the LMB. The associativity list corresponds to the “ibm,associativity” property in a /memory device tree node. A flags word, encoded as with encode-int. This word represents 32 boolean flags. As of this definition, flag bits are defined to correspond to the “ibm,preservable” and “ibm,preserved” properties in a /memory device tree node. This definition allows for additional flags to be added in the future. The following bits in the “flags word” above are defined. Flag Word Name Bit Position Description preserved 0x00000001 If b'0', corresponds to the “ibm,preserved” property having a zero value. If b'1', corresponds to the “ibm,preserved” property having a non-zero value, and the preserved_state bit below indicates the state of preservation. preservable 0x00000002 If b'0', corresponds to the “ibm,preservable” property having a zero value. If b'1', corresponds to the “ibm,preservable” property having a non-zero value. preserved_state 0x00000004 If b'0', corresponds to the “ibm,preserved” property having a 0x1 value. If b'1', corresponds to the “ibm,preserved” property having a 0x2 value (and, in the old binding, the LMB having a status of “fail”). assigned 0x00000008 If b'1', this LMB is assigned to the partition as of boot time. If b'0', this LMB is not assigned to the partition as of boot time. No H_MIGRATE_DMA 0x00000010 If b'0', corresponds to non-existence of the “ibm,no-h-migrate-dma” in the memory node. If b'1', corresponds to existence of the “ibm,no-h-migrate-dma” in the memory node. DRC invalid 0x00000020 If b'0', the DRC field of “ibm,dynamic-memory” property is valid or the DRC values for the set of “ibm,dynamic-memory-v2” property are valid. If b'1', the DRC field of “ibm,dynamic-memory” property is invalid or the DRC values for the set of “ibm,dynamic-memory-v2” property are invalid. Associativity Index 0x00000040 If b'0', the Associativity List Index field of “ibm,dynamic-memory” property or “ibm,dynamic-memory-v2” is valid. If b'1', the Associativity List Index field of “ibm,dynamic-memory” property or “ibm,dynamic-memory-v2” is invalid. Reserved Memory 0x00000080 If b'0', corresponds to the “status” property having a value of “okay”. If b'1', corresponds to the “status” property having a value of “reserved”. Hot-removable Memory 0x00000100 If b'1', this LMB can be “hot-removed”. If b'0', this LMB may fail to be “hot-removed”.

“ibm,dynamic-memory-v2” property name that defines memory subject to dynamic reconfiguration with data in version 2 format. prop-encoded-array: The number N of LMB set entries, encoded with encode-int, followed by N LMB set entries. The number-of-sequential-lmbs encoded with encode-int. The number of LMBs in the set. The starting-logical-address encoded with encode-phys. The logical address of the first LMB in the set. The starting-drc-index encoded with encode-int. The drc-index of the first LMB in the set. The associativity-index encoded with encode-int. All LMBs within the set share the same associativity. The flags word encoded with encode-int. All LMBs within the set share the same flag value. The bits in the flags word are defined in . “ibm,memory-flags-mask” property name that defined which flags in the “flags word” above are defined in this version of this architecture. prop-encoded-array: An integer encoded as with encode-int with all flag bits recognized by this version of this architecture having a b'1' value. For this version, the value will be 0x000000FF. “ibm,memory-preservation-time” property name that defined the time value that would appear in the “ibm,preservable” property in the old bindings for a preservable LMB. prop-encoded-array: An integer value encoded as with encode-int that represents the expected length of time, in minutes, that the platform can sustain the state of power for a preservable LMB. The largest positive number represents an indefinite retention time as provided by such technologies as flash storage. A value zero indicates that no memory will be marked as preservable.

Memory Controller Nodes This section describes memory-controller nodes and their properties. NUMA configurations, have multiple memory-controller nodes in the device tree one for each Central Electronics Complex (CEC). In dynamic reconfiguration NUMA environments, these /memory-controller nodes are subject to standard LoPAR dynamic reconfiguration operations and contain standard LoPAR dynamic reconfiguration properties.

Memory Controller Node Properties No nodes of type memory-controller shall be defined anywhere in the device tree when the platform fully abstracts the memory controller and the OS has no access to the memory controller (typically when running in a partition). Otherwise, one or more nodes of type memory-controller shall be defined as a child of “/” (the root) and shall not have a “ranges” property. The following properties shall apply to each of these nodes. If the platform does not abstract the functions of a platform's multiple memory controllers via firmware (such as RTAS) then the platform shall include a node of type memory-controller for each Memory Controller in the platform. A Memory Controller can also have the “used-by-rtas” property (see ), if it has functions abstracted by RTAS. “device_type” [S] Standard property name that denotes a Memory Controller node. prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be “memory-controller”. “reg” [S] Standard property name defines the base physical address and size of this Memory Controller’s addressable register space. prop-encoded-array: One ( phys-address, size) pair where phys-address is encoded as with encode-phys, and size is encoded as with encode-int. The property value shall be the base physical address and size of this Memory Controller’s register space. “model” [S] Standard property name indicating this Memory Controller’s manufacturer, part number and revision level. prop-encoded-array: Text string, encoded as with encode-string. The value of this property is a vendor dependent string which uniquely identifies this Memory Controller and shall be correlated to its manufacturer, part number, and revision level. (see Core document for more information.) “external-control” [S] property name indicates this Memory Controller’s ability to support the PA external control facility. prop-encoded-int: List of integers, each encoded as with encode-int. The property value, if present, is a list of Resource ID’s the version of the PA external control facility supports. This property shall be present if this Memory Controller supports the PA external control facility, otherwise the property shall be absent. “error-checking” [S] Standard property name defines the error checking capability of the node. prop-encoded-array: a string, encoded as with encode-string, where the value could equal “none”, “ecc”, or “parity”. The value of “#address-cells” for this node is 1. The value of “#size-cells” for this node is 0 because the children of this node do not consume any physical address space.

<literal>IBM,memory-module</literal> Nodes Memory packaged on DIMMs or DIMM like modules are represented in the device tree with IBM,memory-module nodes. These nodes represent physical packages, these packages do not necessarily map directly to a memory address range. No nodes of type IBM,memory-module shall be defined anywhere in the device tree when the platform supports dynamic VPD via the RTAS ibm,get-vpd service. Instead the VPD that would normally be reported via the “ibm,vpd” property in these nodes shall be reported by ibm,get-vpd.

Properties for Memory Modules Memory modules appear as children of the memory node or, for platforms supporting memory DR operations (either logical or physical), the memory-controller node of the device tree. This section defines properties for the IBM,memory-module nodes and additional properties for the memory and memory-controller nodes.

<literal>IBM,memory-module</literal> Node Properties An IBM,memory-module node is a child of the memory node or, for platforms supporting memory DR operations (either logical or physical), the memory-controller node. The “name” of the node is “IBM,memory-module” The “device_type” of the node is “IBM,memory-module” The “reg” standard property for an IBM,memory-module node is its memory module number which is an arbitrary OF selected enumeration. The “ibm,size” property for an IBM,memory-module node is an integer which is less than 4GB and which by itself indicates the size of the memory module, in bytes, if the memory module is smaller than 4GB and if “status” is “okay” or “fail”. If the memory module is larger than or equal to 4GB in size, then the “ibm,size-upper” property for an IBM,memory-module node is present in addition to the “ibm,size” property. This property is an integer which is multiplied times 4GB and then added to the value of the “ibm,size” property to get the size of the module, in bytes. The property “ibm,size-upper” is not required if the memory module size is less than 4GB. The “status” standard property for an IBM,memory-module node may have one of the following string values: “okay” for a good memory module “fail” for a bad memory module “fail-no-matched-pair” for a missing memory module if one of a pair is missing “fail-unsupport” for an unsupported memory module “fail-partial” for a bad memory module where part of the memory on the module is bad and has not been configured and part of the memory is good and has been configured. “fail-excess-memory” for “okay” memory modules that are not configured because they exceed the system memory addressability of the platform. “disabled” for a memory module that has been manually deconfigured. “ibm,mem-banks” property name defines the number of memory banks contained within the memory module. prop-encoded-array: an integer, encoded as with encode-int, which describes whether this is a 1, 2, or 4-bank module, with a corresponding value of 1, 2 or 4 and so on to match the number of banks in the physical device. “ibm,mem-type” property name defines the memory module type. prop-encoded-array: a string, encoded as with encode-string, that describes the type of module, with values of “FP” (Fast Page), “EDO” (Extended Data Out), or “SDRAM” (Synchronous DRAM). “ibm,mem-err-det” property name defines the type of error detection mechanism supported by the module prop-encoded-array: a string, encoded as with encode-string, with values of “none”, “parity”, or “ECC”. “ibm,mem-speed” property name defines the access or clock speed supported by the module, in picoseconds prop-encoded-array: an integer, encoded as with encode-int, which describes the access or clock speed supported by the module, in picoseconds.

Interrupt Controller Nodes This section describes the properties for the LoPAR interrupt controller node. If an interrupt controller node includes the “used-by-rtas” property, then the platform includes firmware code for accessing the interrupt controller. For LSIs, the platform shall adhere to the interrupt structure OF representation.

PowerPC External Interrupt Controller Nodes This section describes the properties for the PowerPC External Interrupt Controller nodes. PowerPC interrupt controllers are normally packaged inside other system chips, however, they are logically represented in the device tree by two or more independent interrupt controller nodes. Each node reports either the interrupt source layer resources that are housed in a single Bus Unit Controller (BUC) e.g. host bridge, or logical equivalent, or a subset of the resources associated with the platform’s interrupt presentation layer. The node per BUC and presentation layer subset divisions provides a foundation for dynamic reconfiguration. At a dynamic reconfiguration event, such as adding an IO drawer, or removing a processor, the interrupt controller nodes associated with the added or removed hardware will also be added or removed. Therefore. platforms should report, in individual nodes, each interrupt controller that occupies a separate physical package. And OSs should expect a fine granularity of interrupt controller reporting. “ibm,interrupt-domain” property name that denotes a PowerPC External Interrupt Domain prop-encoded-array: An integer encoded as with encode-int.

PowerPC External Interrupt Presentation Controller Node Properties The following properties apply to this node. “name” [S] Standard property name that denotes a PowerPC External Interrupt Controller. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “interrupt-controller”. “device_type” [S] Standard property name that indicates an Interrupt Controller. prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be “PowerPC-External-Interrupt-Presentation”. “reg” [S] Standard property name defines the base physical address(s) and size(s) of this PowerPC External Interrupt Presentation layer’s registers. prop-encoded-array: List of ( phys-addr, size ) specifications. Phys-addr is encoded as with encode-phys, and size is encoded as with encode-int. The entries shall represent the base address of a single set of PowerPC External Interrupt Presentation Layer Registers of the Interrupt Management Area. There shall be one entry for each interrupt server queue supported by this unit. The order of the entries shall correspond to the entries in the “ibm,interrupt-server-ranges” property described below. “compatible” [S] Standard property name to define alternate “name” property values. prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, each encoded as with encode-string. The property value shall include “IBM,ppc-xicp”. “ibm,interrupt-buid-size” property name: Defines the number of bits implemented in the concatenation of the BUID fields. prop-encoded-value: An integer in the range of 9 to 20 encoded as with encode-int. As platforms grow in size so as to require use of larger BUIDs (values of the “ibm,interrupt-buid-size” property greater than 9) the platform engineers need to interlock with their OS providers to ensure support. “ibm,interrupt-server-ranges” Property name that defines the interrupt server number(s) and range(s) handled by this unit. prop-encoded-array: List of (server#, range) specifications. Server# is encoded as with encode-int in the range of 0 - 2 the largest value of the “ibm,interrupt-server#-size” property contained in the device tree. Range is encoded as with encode-int. The first entry in this list shall contain the server# associated with the first “reg” property entry. The server# corresponds to a value of a processor’s “ibm,ppc-interrupt-server#s” property. The range shall be the number of contiguous server# s supported by the unit (this also corresponds to the number of “reg” entries). “interrupt-controller” [S] Standard property name to indicate an interrupt (sub-)tree root. prop-encoded-array: <none> The presence of this property indicates that this node represents an interrupt controller. “model” [S] Standard property name indicating this unit’s manufacturer, part number, and revision level. prop-encoded-array: Text string, encoded as with encode-string. The value of this property shall be a string which uniquely identifies the interrupt controller and shall be correlated to the manufacturer, part number, and revision level. This value is device dependent (see the Core document for more information).

PowerPC External Interrupt Source Controller Node Properties Interrupt source controller resources as represented by “interrupt-ranges”, “#interrupt-cells”, and “ibm,interrupt-server#-size” properties may be reported in stand-alone interrupt source controller nodes or in other logical equivalent nodes which contain the “interrupt-controller” property. The following properties apply to these nodes. “name” [S] Standard property name that denotes a PowerPC External Interrupt Controller. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “interrupt-controller”. “device_type” [S] Standard property name that indicates the specific flavor of Interrupt Source Controller. prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be one of the following: “PowerPC-LSI-Source” For Level Sensitive Interrupt source controllers. “PowerPC-MSI-Source” For Message Sensitive Interrupt source controllers such as used with PCI MSI. “reg” [S] Standard property name defines the base physical address(s) and size(s) of this PowerPC External Interrupt Source if any. prop-encoded-array: List of ( phys-addr, size) specifications. Phys-addr is encoded as with encode-phys, and size is encoded as with encode-int. If the “device-type” of the interrupt source controller is “PowerPC-MSI-Source”, then the last “reg” entry shall correspond to the interrupt controller’s 4 byte Message Interrupt Input Port. “compatible” [S] Standard property name to define alternate “name” property values. prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, each encoded as with encode-string. The property value shall include “ibm,ppc-xics”. “interrupt-ranges” [S] Standard property name that defines the interrupt number(s) and range(s) handled by this unit. prop-encoded-array: List of ( int-number, range) specifications. Int-number is encoded as with encode-int. Range is encoded as with encode-int. The first entry in this list shall contain the int-number associated with the first “reg” property entry. The int-number is the value representing the interrupt source as would appear in the PowerPC External Interrupt Architecture XISR. The range shall be the number of sequential interrupt numbers which this unit can generate. “interrupt-controller” [S] Standard property name to indicate an interrupt (sub-)tree root. prop-encoded-array: <none> The presence of this property indicates that this node represents an interrupt controller. “model” [S] Standard property name indicating this unit’s manufacturer, part number, and revision level. prop-encoded-array: Text string, encoded as with encode-string. The value of this property shall be a string which uniquely identifies the interrupt controller and shall be correlated to the manufacturer, part number, and revision level. This value is device dependent (see the Core document for more information). “#interrupt-cells” [S] Standard property name to define the number of cells in an interrupt-specifier within an interrupt domain. prop-encoded-array: An integer, encoded as with encode-int, that denotes the number of cells required to represent an interrupt specifier in its child nodes. The value of this property for the PowerPC External Interrupt option shall be 2. Thus all interrupt specifiers (as used in the standard “interrupts” property) shall consist of two cells, each containing an integer encoded as with encode-int. The first integer represents the interrupt number the second integer is the trigger code: 0 for edge triggered, 1 for level triggered. “ibm,interrupt-server#-size” property name: Defines the number of bits implemented in the concatenation of the server#extension and server# fields. prop-encoded-value: An integer in the range of 8 to 24 encoded as with encode-int. As platforms grow in size so as to require use of the server#extension field (values of the “ibm,interrupt-server#-size” property greater than 8) the platform engineers need to interlock with their OS providers to ensure support.

Additional Node Properties Additional properties and methods are defined in this section for LoPAR binding adapters and/or devices.

Interrupt Properties The properties in this section shall be implemented for any device that can present an interrupt for an LoPAR platform implementation. The platform shall adhere to the definition for the interrupt structure.

Miscellaneous Node Properties This section defines properties which support devices, adapter and buses with geographical information. These properties shall be present for an LoPAR platform. “built-in” [S] Standard property name: Any device that connects to an industry standard I/O expansion bus attached through a non-standard connector. prop-encoded-string: <none>. Note: This property will also include platform ‘riser’ cards. “used-by-rtas” [S] Standard property name: Indicates the device can be in use by an RTAS Function Call. prop-encoded-int: Presence of property indicates a device may have an I/O or resource conflict with a RTAS Function Call. The use of the “slot-names” property defined below is deprecated in favor of the “ibm,loc-code” property. “slot-names” [S] property name: Describes external labeling of adapter/device connectors. prop-encoded-array: An integer, encoded as with encode-int, followed by a list of strings, each encoded as with encode-string. The integer portion of the property value is a bitmask of available connectors; for each connector associated with the adapter/device, the bit corresponding to that connector’s ID number is set from least-significant to most-significant ID number. The number of following strings is the same as the number of connectors; the first string gives the platform nomenclature or label for the connector with the smallest ID number, and so on. Note: Each device that has a connector should identify the order and contents of the list of strings in a binding. “ibm,loc-code” [S] property name to provide location code(s) for the Field Replacable Unit. prop-encoded-array: an arbitrary number of strings, encoded as with encode-string. “ibm,vpd” property name to provide Vital Product Data (VPD) information as defined in . prop-encoded-array: the concatenation, with encode+, of one or more pairs of elements, the first element of each pair being an integer (representing the length of the second element) encoded as with encode-int, and the second element of each pair being a series of bytes (the VPD data) encoded as with encode-bytes. “ibm,loc-code-map” prop-name to identify that the interface may have child nodes, which may or may not be present in the device tree, that have a physical location code based on their unit-address. prop-encoded-array: A list of pairs (unit-address, location-code). The unit-address is the child device node's “reg” property string-encoded according to the parent node's architecture and encoded as with encode-string. The location-code is the child device node's “ibm,loc-code” property encoded as with encode-string. If a child device under this node has a matching unit-address, the location code corresponds to the physical location of that child device.

<literal>/aliases</literal> Node A device alias, or simply alias, is a shorthand representation of a device-path. Aliases are properties of the aliases node, encoded as with encode-string. Aliases are typically used by a user to facilitate not specifying a long path name at the User Interface ‘ok’ prompt. An implementation of OF for an LoPAR platform shall provide the following aliases as properties of the aliases node, if the corresponding device exists: “disk” [S] property name indicating the device path of the factory default disk that is the preferred boot disk Implementation Note: The preferred boot disk should be the disk that results in the fastest boot time. Implementations might automatically spin up a disk at system power on and provide mechanisms for firmware to report that disk in this property. for the platform. “tape” [S] property name indicating the device path of the factory default tape. “cdrom” [S] property name indicating the device path of the factory default CDROM. “keyboard” [S] property name indicating the device path to the keyboard to be used for the User Interface. “mouse” [S] property name indicating the device path to the mouse to be used for the User Interface. “screen” [S] property name indicating the device path to the screen to be used for the User Interface. “pc-keyboard” [S] property name indicating the device path of the factory default PC-style keyboard. “pc-mouse” [S] property name indicating the device path of the factory default PC-style mouse. “adb-keyboard” [S] property name indicating the device path of the factory default ADB-style keyboard. “adb-mouse” [S] property name indicating the device path of the factory default ADB-style mouse. “scsi” [S] property name indicating the device path of the factory default built-in SCSI device. “com1” [S] property name indicating the device path of the factory default 16550-style serial port known as “com1.” “com2” [S] property name indicating the device path of the factory default 16550-style serial port known as “com2.” “scca” [S] property name indicating the device path of the factory default SCC-style serial port known as “SCCA.” “sccb” [S] property name indicating the device path of the factory default SCC-style serial port known as “SCCB.” “floppy” [S] property name indicating the device path of the factory default floppy drive. “net” [S] property name indicating the device path of the factory default built-in network interface controller. “rtc” [S] property name indicating the device path of the factory default real-time-clock chip. “nvram” [S] property name indicating the device path of the factory default NVRAM.

<literal>/event-sources</literal> Node The /event-sources node describes the possible RTAS Error and Event Classes for interrupts. The /event-sources node shall be defined to be a child of the root device tree node if the platform supports any event interrupts. The following properties shall be defined for this node: “name” [S] Standard property name that denotes the Event Sources. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “event-sources”. When events are reported as virtual interrupts there shall be a node of device_type “PowerPC-External-Interrupt-Presentation” from which the virtual interrupt source BUID size can be obtained. Also the event-sources node represents the interrupt source node for virtual event interrupts and thus the following properties shall be defined for this node: “interrupt-controller” [S] Standard property name: to indicate the events interrupt tree root. prop-encoded-array: <none> The presence of this property indicates that this node represents a source of virtual interrupts. Encoded with encode-null. “#interrupt-cells” [S] Refer to the definition of the “#interrupt-cells” property for nodes of device_type “PowerPC-LSI-Source” for information about the definition of this property for virtual event interrupts. “interrupt-ranges” [S] Refer to the definition of the “interrupt-ranges” property for nodes of device_type “PowerPC-LSI-Source” for information about the definition of this property for virtual event interrupts. Children of /event-sources present the interrupt specifiers associated with the reporting of platform events. LoPAR platforms have historically implied the default value of “#interrupt-cells” of 1 to report the associated interrupt specifiers without the interrupt trigger specifier. However, all new designs shall present interrupt specifiers with explicit trigger level values.

Child nodes of the Event Sources Node The following specify standard child nodes of the /event-sources node. These nodes could be present in an LoPAR platform. Children of the /event-sources node specify the interrupt specifiers associated with the reporting of platform events. Interrupt designs shall use the 1275 standard “interrupts” property as configured to report the interrupt specifier for the platforms PowerPC interrupt controller. The interrupt specifiers if the “interrupts” property indicates one or more interrupt source numbers that are used to report event conditions.

internal-errors The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. “name” [S] Standard property name that denotes the internal error’s events. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “internal-error”.

epow-events The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. “name” [S] Standard property name that denotes the EPOW events. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “epow-events”.

ibm,io-events The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. “name” [S] Standard property name that denotes the I/O sub-system events. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “ibm,io-events”.

hot-plug-events The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. “name” Standard property name that denotes the hot-plug events. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “hot-plug-events”.

<literal>/reserved</literal> Node This section defines a reserved node which shall have a “reg” property which allocates addresses (on the bus of which it is a child) which is intended to be a place to identify hardware registers that do not otherwise belong to a recognized device. “name” [S] Standard property name that denotes reserved addresses that do not belong to a recognized device. prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be “reserved”. “device_type” [S] Standard property name that indicates the device type. prop-encoded-array: Text string, encoded as with encode-string. The value of this property shall be “reserved”. “reg” [S] Standard property name defines a hardware register address and range of addresses not intended for OS (OS) use. prop-encoded-array: List of ( phys-addr, size) specifications. Phys-addr is a (phys.lo ... phys.hi) sequence equal to #address-cells, encoded as with encode-phys. size is a sequence equal to #size-cells encoded as with encode-size. The first entry in this list shall be a hardware register address ( phys-addr) and a range of hardware addresses ( size) that is not intended for OS usage. Successive entries in this list shall be additional hardware addresses not intended for OS usage.

<literal>/chosen</literal> Node This section lists additional properties as required under the /chosen node with the following text in a manner that is consistent with , Section 3.5. “nvram” [S] Standard property name that defines the package Ihandle for CHRP NVRAM. prop-encoded-array: an integer, as encoded with encode-int, that is the package Ihandle the CHRP NVRAM. Note: The nvram Node identified in the /chosen Node shall support a size method as specified in , Section 7.2. The size method will return a value that is the total platform NVRAM size. “ibm,rpa-client-config” property name that defines the processed fields of the client program’s IBM,RPA-Client-Config ELF note section. prop-encoded-array: an array of integers encoded as with encode-int, that consist of the fields of the note section that the firmware processed prior to loading the client program. “ibm,architecture-vec-5” property name: that presents the values of the option vector #5 negotiated by the ibm,client architecture-support method. Presence of this property signifies that the client program load module invoked the ibm,client architecture-support method. prop-encoded-array: An array of bytes having the format of the fifth option vector from representing the value chosen by the ibm,client architecture-support method. “ibm,client-architecture-support-reboot” property name: that indicates that one or more reboots have occurred in this boot sequence in order to adjust the platform settings to match the specification in the “ibm,client-architecture-support” open firmware method or the IBM,RPA-Client-Config ELF header note. Note this property is not included for the first boot in a sequence. prop-encoded-array: encoded as with encode-int that specifies the number of reboots that have occurred in this boot sequence in order to adjust the platform settings to match the specification in the “ibm,client-architecture-support” open firmware method or the IBM,RPA-Client-Config ELF header note.

<literal>/vdevice</literal> Node The node of type vdevice is a child of the root node. It is only present in trees that also include the “ibm,hypertas_functions” property. It, and its children represent the virtualized devices that are implemented by the platform firmware. Virtualized devices do not surface to a client program a direct hardware interface. They do not appear to take up space in the client program’s address map. Standard property names associated with the /vdevice node have special values as specified below. “#address-cells” [S] Standard property name encoded as with encode-int that specifies the number of cells required to represent a child bus address. Shall have the value of 1. “#size-cells” [S] Standard property name encoded as with encode-int that specifies the number of cells required to encode the size field of a child’s reg property. Shall have the value of 0 indicating that no child node may actually take physical address space. “name” [S] Standard property name string encoded as with encode-string that defines the name of node. The value shall be the string “vdevice”. “device_type” [S] Standard property name string encoded as with encode-string that defines the device type of the node. The value shall be the string “vdevice”. “ibm,max-virtual-dma-size” Vendor unique property name indicating the maximum size virtual dma transfer size supported by the platform prop-encoded-array: a single integer encoded as with encode-int. “ibm,migration-control” property name that indicates when platform firmware supports the ability for an I/O server partition to delay the migration of a partition to a different server in order to let any in progress I/O to be completed. Specifically, this property indicates that the DISABLE_MIGRATION and ENABLE_MIGRATION subfunctions of the H_VIOCTL hypervisor call are supported. prop-encoded-array: None, this is a name only property. “ibm,reserved-virtual-addresses” Vendor unique property name indicating ranges of the client program virtual address space that are reserved for platform use. prop-encoded-array: one or more pairs of abbreviated-virtual-address, virtual-address-length specifications representing the origin and length respectively of a reserved virtual address range. abbreviated-virtual-address: Consists of two integers encoded as with encode-int representing the high order and low order 32 bits respectively of the 64 bit abbreviated virtual address. The full virtual address is the abbreviated-virtual-address concatenated with 3 low order bytes of 0x00. virtual-address-length: Consists of a single integer encoded as with encode-int representing the number of consecutive 4K pages contained within the range.

Children of the <literal>/vdevice</literal> Node The children of the /vdevice node represent the individual virtual devices. Children of the /vdevice node that support dma operations contain a the “ibm,my-dma-window” property as defined below: “ibm,my-dma-window” property name that defines the bus address window(s) that this IOA may use for its dma. prop-encoded-array: One or more ( logical-I/O-bus-number, phys, size) triple(s) where the logical bus number is a one cell cookie representing the unique range of TCE entries assigned to this IOA encoded as with encode-int, the number of cells for phys corresponds to the node’s “ibm,#dma-address-cells” value while the number of cells for size corresponds to the “ibm,#dma-size-cells” for this node. The first triple represents the TCE range available for mapping local memory, while the second triple, if it exists, is where remote memory mapped by remote partitions appears. The size field of the second triple shall be equal to the size field of the corresponding remote partition’s first triple. The “ibm,my-dma-window” property is the per device equivalent of the “ibm,dma-window” property found in nodes representing bus bridges. Children of the /vdevice node share the ability to display unique capabilities as represented by the following properties. “ibm,async-dma-required” property name indicates that the virtual device requires the use of asynchronous virtual DMA interfaces (see for definition of asynchronous virtual DMA interfaces). prop-encoded-array: None, this is a name only property. Children of the /vdevice node which act a a server to other virtual client devices, display the following property. “ibm,vserver” property name indicates that the virtual device is a server to virtual devices. prop-encoded-array: None, this is a name only property. “ibm,mac-address-filters” property name specifies the number of non-broadcast multicast MAC filters supported by the implementation. prop-encoded-array: an integer in the range of 0-255 encoded as with encode-int. “ibm,trunk-adapter” property name that indicates that the virtual device is a trunk adapter server to the logical LAN. prop-encoded-array: None, this is a name only property. “ibm,illan-options” property name: The existence of this property is required when any of the ILLAN sub-options are implemented and indicates that the H_ILLAN_ATTRIBUTES hcall() is implemented, and that hcall() is then used to determine which ILLAN options are implemented. prop-encoded-array: None, this is a name only property. “ibm,vf-loc-code” Vendor unique property name indicating the physical device virtual function upon which the vnic-server runs. The value is that of the “ibm,loc-code” property of the physical device virtual function. prop-encoded-array: an arbitrary number of strings, encoded as with encode-string. “ibm,vnic-mode” Vendor unique property name that represents the operational mode in which the vnic-server runs. prop-encoded-array: a single byte, encoded as with encode-bytes. Defined values: 0: backing device is dedicated to one VNIC client 1: backing device is shared by multiple VNIC clients 2-255: reserved “ibm,vnic-client-mac” Vendor unique property name that represents the MAC address of a given vNIC server's client. prop-encoded-array: 6 bytes, encoded as with encode-bytes.

Virtual Teletype Device The virtual teletype device allows communication through the platform’s attached Hardware System Console. There is one such virtual device node for each virtual terminal enumerated by the “ibm,termno” property. The unit addresses of the virtual teletype devices shall correspond to the enumeration presented in the “ibm,termno” property. Such virtual terminals, as represented by the “ibm,termno” property, are intended for the use of the client program and shall not be marked “used-by-rtas”. Similarly they may be “chosen” as the default input and output device. “name” [S] Standard property name encoded as with encode-string that defines the device name. The value shall be the string “vty”. “reg” [S] Standard property name to define a unit address for the node. One ( phys-addr, size) pair. The phys-addr is the unit address of the device (corresponding to one of the virtual terminals enumerated by the “ibm,termno” property), and the size shall have a length of zero. “device_type” [S] Standard property name encoded as with encode-string to specify the device type. The value shall be the string “serial” indicating that the device emulates a serial terminal. “compatible” [S] Standard property name encoded as with encode-string to specify the device driver compatibility. The value shall be one of the strings specified in . Virtual tty compatibility strings Compatible property String Value Comments “hvterm1” Standard client virtual tty protocol “hvterm2” Standard server virtual tty protocol “hvterm-protocol” Client virtual tty protocol extended for control of modems etc.

See for further detail on this virtual device.

Children of <literal>/vdevice</literal> node defined in other documents Like children of the pci bus node, children of /vdevice may be defined by their own binding documents or via binding sections/tables in their device specifications. For example, the binding information for the LoPAR Interpartition Logical LAN, Virtual SCSI, and Virtual Terminal can be found in the appropriate sections of this document. The virtualization of traditional physical devices repositions their associated device tree nodes to be children of /vdevice. Examples include NVRAM and Real Time Clock (RTC) devices which are defined by .

Barrier Synchronization Facility This section describes the OF node that represents the optional Barrier Synchronization Register (BSR) facility. If the platform provides a BSR facility it provides the ibm,bsr node as a child of / (root). If the platform provides a client program with multiple independent facilities, it represents each such facility with a separate node. A given facility may have multiple representations through parallel windows. Each window of a given facility is represented by a separate “reg” property value. The following properties are the minimum required, optional support such as dynamic reconfiguration will add properties per requirements called out in the . “name” [S] Standard property name encoded as with encode-string that defines the device name. The value shall be the string “ibm,bsr” for legacy implementations and “ibm,bsr2” for POWER8 implementations and beyond. “reg” [S] Standard property name to define the addresses for the facility window(s). prop-encoded-array: One or more ( phys-addr, size) pair(s). The phys-addr, encoded as with encode-phys, is the starting address (4 K aligned) of the window. The size, encoded in the number of cells specified by “#size-cells” of the parent, is the length of the corresponding window. “device_type” [S] Standard property name encoded as with encode-string to specify the device type. The value shall be the string “ibm,bsr”. “compatible” [S] Standard property name encoded as with encode-string to specify the device driver compatibility. The value shall be the string “ibm,bsr”. “ibm,#lock-bytes” property name: Indicates the number of lock bytes per line of the BSR facility. prop-encoded-array: One or more integers encoded as with encode-int. When the facility has multiple windows, as represented by multiple values of the “reg” property, then there is a corresponding number of integers, each integer representing the number of lock bytes per line of the corresponding window. “ibm,lock-stride” property name: Indicates the number of bytes between the beginning of lock lines in the BSR facility. prop-encoded-array: One or more integers encoded as with encode-int. When the facility has multiple windows, as represented by multiple values of the “reg” property, then there is a corresponding number of integers, each integer representing the number of bytes to the beginning of the next lock line in the corresponding window.

Nodes of device_type <literal>“block”</literal> and <literal>“byte”</literal> This section describes the OF nodes that provide access to storage devices in block or byte commands. This applies to such nodes with and without a “reg” property. “ibm,write-supported” property name: Indicates the driver supports write functionality and has been verified by IBM. The use of the write function without this property is discouraged. prop-encoded-array: None, this is a name only property. “ibm,16byte-cdb-supported” property name: Indicates the driver supports using the 16 byte Command Descriptor Block format, which is needed to access above 2 TB on 512 byte block-sized media. prop-encoded-array: None, this is a name only property.

<literal>/ibm,platform-facilities</literal> The node of type ibm,platform-facilities is a child of the root node. It and its children represent the non-CPU platform computational facilities that are available. Platform facilities do not take up space in the client program’s address map. Standard property names associated with the /ibm,platformfacilities node have special values as specified below. “#address-cells” [S] Standard property name encoded as with encode-int that specifies the number of cells required to represent a child bus address. Shall have the value of 1. “#size-cells” [S] Standard property name encoded as with encode-int that specifies the number of cells required to encode the size field of a child’s reg property. Shall have the value of 0 indicating that no child node may actually take physical address space. “name” [S] Standard property name string encoded as with encode-string that defines the name of node. The value shall be the string “ibm,platform-facilities”. “device_type” [S] Standard property name string encoded as with encode-string that defines the device type of the node. The value shall be the string “ibm,platform-facilities”. Some platform facilities configurations allow multiple facilities to share a common pool of interrupt server numbers. Individual operations specify which interrupt server number from the pool shall be used to signal completion of the operation. To represent such a configuration, the /ibm,platformfacilities node may either represent an interrupt source controller for its children or the interrupt source controller associated with the shared pool may be represented by a PowerPC External Interrupt Source Controller Node as an additional child node of the /ibm,platform-facilities node (). Additionally, the node representing the platform facilities Interrupt Source Controller shall contain the “ibm,interrupt-pool” property, and all platform facilities that share the common pool of interrupts shall contain the “ibm,shared-interrupt-pool” property. “ibm,interrupt-pool” property name: that indicates this interrupt controller provides a shared pool of interrupt source numbers. property encoded array: single cell encoded as with encode-int that represents the type of shared interrupt pool being represented: Defined values are: 0 with all other values reserved. “ibm,max-async-ops-per-processor” property name: that indicates for the partition the allowed maximum number of outstanding operations for the platform facility based upon the number of processors currently allocated to the partition. The total allowable number of such operations outstanding across all partition processors is the product of the value of “ibm,max-async-ops-per-processor” and the number of nodes of type cpu in the current partition device tree. property encoded array: single cell encoded as with encode-int

Children of the <literal>/ibm,platform-facilities</literal> Node The children of the /ibm,platform-facilities node represent the individual platform facilities. Standard property names associated with the children of the /ibm,platform-facilities node have special values as specified below. Note the children of the /ibm,platform-facilities node shall contain the following standard properties with their standard definitions: “compatible” “name” The defined Values for the “name” property of children of /ibm,platform-facilities are (were # is the version number of the interface): ibm,random-v# Random number generator ibm,compression-v# Compression/Decompression engine ibm,sym-encryption-v# Symmetric encryption/decryption engine ibm,asym-encryption-v# Asymmetric encryption/decryption engine ibm,memory-utilization-instrumentation-v# Memory usage information “status” Optionally the children of the /ibm,platform-facilities node may contain as appropriate the following standard properties with their standard definitions: “interrupts” Additionally the children of the /ibm,platform-facilities node may contain as appropriate the following unique properties: “ibm,resource-id” property name: that indicates the platform facility resource identification handle. property encoded array: single cell encoded as with encode-int “ibm,max-sync-cop” property name: that indicates the maximum characteristics of the parameters for a synchronous call of the platform facility. These characteristics are represented as a series of integers encoded as with encode-int that may grow over time as platform facilities evolve. The absence of this property indicates that synchronous operations are not allowed for the given child. property encoded array: a series of zero or more or more cells each encoded as with encode-int. The interpretation of the series of integers is unique per the value of the “name” property: For the Random number generator: NULL value indicating that all calls are synchronous For the compression/decompression engine: Two series of cells the first series of cells represents the maximums that can be synchronously compressed. The second series of cells represents the maximums that can be synchronously decompressed. The first cell in each series contains the count of the number of data length, scatter/gather elements pairs that follow – each being of the form One cell data byte length One cell total number of scatter/gather elements For the symmetric encryption/decryption engine: the series of cells report for each function code (FC) and mode combination the maximum amount of data and scatter/gather list elements that can be processed with a given key length. Thus the array consists of 1-N sub sequences each of the form: First cell contains the FC field Second cell contains the mode field Third cell contains the count of the number of key length, data length, scatter/gather elements triples that follow – each being of the form: One cell key bit length One cell data byte length One cell total number of scatter/gather elements “ibm,max-sg-len” property name: that indicates the maximum byte length of a scatter/gather list for the platform facility. property encoded array: single cell encoded as with encode-int “ibm,shared-interrupt-pool” property name: that provides an indirect pointer to the node representing the shared interrupt pool used by this facility. property encoded array: the phandle of the node representing the PowerPC External Interrupt Source Controller that sources the interrupts of the shared interrupt pool used by this facility. For the memory utilization instrumentation facility node the following properties are defined: “ibm,mui-associativity-mapping” property name to define the mapping between Memory Usage Instrumentation Affinity Log Array entries and their associated associativity strings. property encoded array: An integer (L) encoded as with encode-int followed by L sets ALA map entries. Each ALA map entry consisting of: An integer (ALAentry) encoded as with encode-int as would be found in the affinity_log record for the return buffer from the H_RETURN_PAGEINFO hcall() followed by; An integer (M) encoded as with encode-int that represents the type of source of the reference (defined values are presented below). Sources of a general type are grouped together, so that if the client program does not recognize a given specific type, it can still categorize via the more general type of source: 0-100,000,000 CPU 100,000,001 – 200,000,000 I/O Bridge 200,000,001 – 300,000,000 Platform Service Device All other values reserved (may be grouped together as an unknown source type). Followed by: An integer (N) encoded as with encode-int followed by N associativity lists. Each associativity list consisting of a number of entries integer (P) encoded as with encode-int followed by P integers encoded as with encode-int each representing an associativity domain number. “ibm,mui-ranges” property name to define the implementation specific ranges of memory utilization instrumentationmeasures. property encoded array: An integer (N) encoded as with encode-int which communicates the number of pairs of range values, each being an integer encoded as with encode-int which represent the implementation limits of a given measure. See for details. The reader is to ignore values pairs beyond those it was designed to use. If the value of N is zero the MUI measures are not available. <emphasis role="bold"><literal>“ibm,mui-associativity-mapping”</literal></emphasis> range limits Pair # 1 MIN/MAX The minimum and maximum supported value of the HUC field which is the power of 2 multiplier of microseconds that defines the History Bit Array update period. 2 0/MAX The number of bits implemented in the HBA. 3 0/MAX Access rate in accesses per millisecond. 4 0/MAX Page Age; the MAX value is the number of Page Age Granules which saturates the page age counter. 5 0/MAX Remote Reference; the MAX value is the number of implemented ALA entries.